The process in this article needs to be done once per platform. Once you have the code, you can apply it every time to create a ToC. Note that if the platform changes something, you may need to adjust the script.

Table of Contents

• Browser Dev Tools

• JavaScript Console

• Understanding the DOM Structure

• Creating TOC in Markdown

• How to create an HTML TOC?

• Copy the HTML code for the editor

• What to do if I don’t have headers?

  • Create Table of Contents for DEV.to

• Conclusion

Browser Dev Tools

Dev Tools is an extension to the browser that can allow you to inspect and manipulate the DOM (Document Object Model), which is a representation of the HTML the browser keeps in memory in the form of a tree. It also gives access to the JavaScript console, where you can write short code snippets to test something. It has a lot more features, but we'll only use those two.

To open Dev Tools (in Google Chrome), you can press F12 or right-click on the page with your mouse and click Inspect.

Above is the screenshot of DevTools with a preview of this article. On the right, you can see a selected h1 HTML tag (the title) and CSS applied to that tag. The tree structure you see is the DOM.

JavaScript Console

We will need to have access to the JavaScript console. To open the console in Google Chrome, you can use F12, right-click on the page and select Inspect from the context menu, or use the shortcut CTRL+SHIFT+C (Windows, Linux) or CMD+OPTION+C (Mac).

In Chrome DevTools, you can pick the Console tab at the top of the DevTools. But this will hide the DOM tree. It’s better to open the bottom drawer. You need to click the 3 dots in the top right corner and pick “show console drawer”.

The Dev Tools will look like this:

The console is a so-called Read-Eval-Print-Loop. A classic interface, where you type some commands, here JavaScript code, and when you press enter, the code is executed in the context of the page the DevTools is on.

Above, you can see a page alert executed from the console.

Understanding the DOM Structure

The first step to create a ToC is to inspect the DOM and find the headers. They are usually H1…H6 tags. H1 is often the title of the page. In an ideal world, it would always be.

In my case, the header looks like this:

<h2 id="heading-dev-tools">Dev Tools</h2>

The article only has H2 tags, but later in the article, I will also explain how to create a nested ToC.

Now with DevTools, we can write code that will find every header:

document.querySelectorAll('h2[id], h3[id], main h4[id]');

In the case of my article on freeCodeCamp, it returned this output:

NodeList(5) [h2#heading-dev-tools, h2#heading-javascript-console, h2#heading-understanding-the-dom-structure, h2#trending-guides.col-header, h2#mobile-app.col-header]

First, it’s a NodeList that we need to convert to an Array. Second is that besides our headers that we have so far, we also have two headers that are part of the website and not the main content. So we need to find out the single element that is the parent of the headers we need.

You can right-click on the white page that contains the article and pick Inspect Element. In our case, it found an element <main>. So we can rewrite our selector as:

document.querySelectorAll('main h2[id], main h3[id], main h4[id]');

And now it returns our headers and nothing more.

How to Create the ToC in Markdown

A lot of blogging platforms support Markdown, so it'll be the first thing we'll create.

First, we'll convert the Node list to an array. We can use the spread operator:

[...document.querySelectorAll('main h2[id], main h3[id], main h4[id]')];

Then we can map over the array and create the Markdown links that point to the given header.

const headers = [...document.querySelectorAll('main h2[id], main h3[id], main h4[id]')];

headers.map(function(node) {
    // H2 header should have 0 indent
    const level = parseInt(node.nodeName.replace('H', '')) - 2;
    const hash = node.getAttribute('id');
    const indent = ' '.repeat(level * 2);
    return `\({indent}* [\){node.innerText}](#${hash})`;
});

The output looks like this:

(4) ['* [Dev Tools](#heading-dev-tools)', '* [JavaScript Console](#heading-javascript-console)', '* [Understanding the DOM Structure](#heading-understanding-the-dom-structure)', '* [What to do if I don’t have headers?](#heading-what-to-do-if-i-dont-have-headers)']

To get the text, we can join the array with a newline character and use console.log to display the output. If we don’t use console.log, it will show a string with \n characters.

const headers = [...document.querySelectorAll('main h2[id], main h3[id], main h4[id]')];

console.log(headers.map(function(node) {
    // H2 header should have 0 indent
    const level = parseInt(node.nodeName.replace('H', '')) - 2;
    const hash = node.getAttribute('id');
    const indent = ' '.repeat(level * 2);
    return `\({indent}* [\){node.innerText}](#${hash})`;
}).join('\n'));

The output for this article will look like this:

* [Dev Tools](#heading-dev-tools)
* [JavaScript Console](#heading-javascript-console)
* [Understanding the DOM Structure](#heading-understanding-the-dom-structure)
* [Creating TOC in Markdown](#heading-creating-toc-in-markdown)
  * [This is fake header](#heading-this-is-fake-header)

I created one fake subheader. Platforms, even when not supporting Markdown when writing articles, often support Markdown when copy-pasted. The ToC at the top of the article was created by copying and pasting markdown generated with the last JavaScript snippet.

How to Create an HTML ToC

If your platform doesn’t support Markdown (like Medium), you can create HTML, preview that HTML, and copy the output to the clipboard. Pasting that into the editor of the platform you're using should keep the formatting.

To convert Markdown to HTML, you can use any online tool, but you'll see how to create it yourself in the snippet. It will be faster after you create the code.

const headers = [...document.querySelectorAll('main h2[id], main h3[id], main h4[id]')]

function indent(state) {
    return ' '.repeat((state.level - 1) * 2);
}

function closeUlTags(state, targetLevel) {
    while (state.level > targetLevel) {
        state.level--;
        state.lines.push(`${indent(state)}</ul>`);
    }
}

function openUlTags(state, targetLevel) {
    while (state.level < targetLevel) {
        state.lines.push(`${indent(state)}<ul>`);
        state.level++;
    }
}

const result = headers.reduce((state, node) => {
    const level = parseInt(node.nodeName.replace('H', ''));

    closeUlTags(state, level);
    openUlTags(state, level);
    
    const hash = node.getAttribute('id');
    state.lines.push(`\({indent(state)}<li><a href="#\){hash}">${node.innerText}</a></li>`);
    return state;
}, { lines: [], level: 1 });

closeUlTags(result, 1);

console.log(result.lines.join('\n'));

This is the output of the code in this article:

<ul>
  <li><a href="#heading-table-of-contents">Table of Contents</a></li>
  <li><a href="#heading-dev-tools">Dev Tools</a></li>
  <li><a href="#heading-javascript-console">JavaScript Console</a></li>
  <li><a href="#heading-understanding-the-dom-structure">Understanding the DOM Structure</a></li>
  <li><a href="#heading-creating-toc-in-markdown">Creating TOC in Markdown</a></li>
  <li><a href="#heading-how-to-create-html-toc">How to create HTML TOC</a></li>
  <ul>
    <li><a href="#heading-level-3">Level 3</a></li>
    <ul>
      <li><a href="#heading-level-4">Level 4</a></li>
    </ul>
  </ul>
  <li><a href="#heading-what-to-do-if-i-dont-have-headers">What to do if I don’t have headers?</a></li>
</ul>

I added a few headers at the end, so you can see that it will work for any level of nested headers. Note that we also have the ToC as the first element on the list.

Copy the HTML code for the editor

Most so-called WYSIWYG editors are using HTML, and you should be able to copy the output of HTML code with formatting and paste it into that editor. The easiest is to just save that into a file, open that file, and select the text:

What to Do If I Don’t Have Headers?

You need to find anything that can be targeted with CSS. If they are p tags with a specific class (like header), you can use p.header instead of h2.

How to Create a Table of Contents for DEV.to

If you have a different DOM structure, you can use different DOM methods to extract the element you need. For example, on DEV.to, the headers look like this:

<h2>
  <a name="overview" href="#overview">
  </a>
  Overview
</h2>

So the selector needs to be just main h2. But when you execute this code:

[...document.querySelectorAll('main h2, main h3, main h4')];

You will see that there are way more headers than the content of the document. Luckily, we can use a new selector in CSS :has(). The final selector for one header can look like this: main h2:has(a[name]).

Here is the full code:

const selector = 'main h2:has(a[name]), main h3:has(a[name]), main h4:has(a[name])';
const headers = [...document.querySelectorAll(selector)];

console.log(headers.map(function(node) {
    // H2 header should have 0 indent
    const level = parseInt(node.nodeName.replace('H', '')) - 2;
    // this is how you get the hash
    // you can also access href attribute and remove # from the output string
    const hash = node.querySelector('a').getAttribute('name');
    const indent = ' '.repeat(level);
    return `\({indent}* [\){node.innerText}](#${hash})`;
}).join('\n'));

Conclusion

Creating a table of contents can help your readers digest your article. Since most people don’t read the whole article, they only scan for what they need. You can also find a lot of articles about its impact on SEO. So it’s always worth adding one if the article is longer.

And as you can see, creating a ToC is not that hard with a bit of web development knowledge.

If you like this article, you may want to follow me on Social Media: (Twitter/X, GitHub, and/or LinkedIn). You can also check my personal website and my new blog.

In my Lisp interpreter, the brackets could be mixed like this:

(let [(x 10])
  [+ x x)]

The above code is an example of an S-Expression where we have tokens, a sequence of characters with meaning (like name let or number 10), and brackets/parentheses. However, the code is not valid because it mixes pairs of parentheses and brackets.

(let [(x 10)]
  [+ x x])

This is the proper Lisp syntax (if brackets are supported), where opening parentheses always match closing parenthesis and opening brackets always match closing brackets.

In this article, I'll show you how you can detect if the input is the second valid S-Expression and not the first invalid S-Expression.

We will also handle cases like this:

(define foo 10))))

In the code above, you see invalid syntax with more closing than opening parentheses.

So in simple terms, we will detect if pairs of opening and closing characters like (), [], and {} match inside the string like "[foo () {bar}]".

The solution to this problem can be useful when implementing a Lisp parser, but you can also use it for different purposes (like some kind of validation or part of a math expression evaluator). It's also a good exercise.

NOTE: to understand this article and code, you don't need to know anything about Lisp. But if you want some more context, you can read this article: What is Lisp and Scheme?

Pairing with the Stack Data Structure

You may think that the simplest way to solve this problem is using Regular Expressions (RegExp). It may be possible to use Regex for simple cases, but soon it will get too complex and have more problems than it solves.

Actually, the easiest way of pairing opening and closing characters is using the stack. Stack is the simplest data structure. We have two basic operations: push, for adding an item to the stack, and pop, for removing an item.

This works similarly to a stack of books. The last item that you put onto the stack will be the first one that you take out.

You can read more about this data structure from this article: Data Structures 101: Stacks.

With a stack, it's easier to process (parse) the characters, which have a beginning and end, like XML tags or simple parentheses.

For example, say we have this XML code:

<element><item><sub-item>text</sub-item></item></element>

When we use the stack, the last tag we open (inner <sub-item> for example) will always be the first we need to close (if the XML is valid).

So if we use the stack, we can push the item <sub-item> when we open it, and when we need to close it we can pop it from the stack. We only need to make sure that the last item on the stack (which is always the opening tag) matches the closing one.

We will have exact same logic with parentheses.

Note that if we have XML self-closing tags, we can skip them since they are open and automatically closed.

Arrays in JavaScript have both methods (push and pop), so they can be used as a Stack. But it's more convenient to create an abstraction in the form of a class, so we can add additional methods like top() and is_empty() that are easier to read.

But even if we didn't add new methods, it's always better to create abstractions like this, because it makes the code simpler and easier to read.

Most developers know common data structures and will immediately recognize them and not need to think about them. The most important thing with programming is forgetting not related stuff that are required at any given moment. The human memory is limited and can only hold about 4±1 items at the same time. You can read more about short-term memory on Wikipedia.

class Stack {
    #data;
    constructor() {
        // creating new empty array as hiden property
        this.#data = [];
    }
    push(item) {
        // push method just use native Array::push()
        // and add the item at the end of the array
        this.#data.push(item);
    }
    len() {
        // size of the Stack
        return this.#data.length;
    }
    top() {
        // sice the items are added at the end
        // the top of the stack is the last item
        return this.#data[this.len() - 1];
    }
    pop() {
        // pop is similar to push and use native Array::pop()
        // it removes and returns the last item in array
        return this.#data.pop();
    }
    is_empty() {
        // this comment shortcut !0 is true
        // since 0 can is coerced to false
        return !this.len();
    }
}

The above code uses ES6 (ES2015) class and ES2022 private
properties.

The Parentheses Matching Algorithm

Now I will describe the algorithm (steps) needed to parse the parentheses.

We need a loop that will go through each token – and it's best if all other tokens are removed before processing.

When we have an opening parenthesis, we need to push that element into the stack. When we have a closing parenthesis, we need to check if the last element on the stack matches the one we are processing.

If the element is matching, we remove it from the stack. If not, it means that we have messed up parentheses, and we need to throw an exception.

When we have a closing bracket, but there is nothing on the stack, we also need to throw an exception, because there is no opening parenthesis that matches the closing one we have.

After checking all the characters (tokens), if something is left of the stack, it means that we didn't close all the parentheses. But this case is ok, because the user may be in the process of writing. So in this case, we return false, not an exception.

If the stack is empty, we return true. This means that we have a complete expression. If this was an S-Expression, we could use the parser to process it, and we would not need to worry about invalid results (of course if the parser was correct).

The Source Code

function balanced(str) {
    // pairs of matching characters
    const maching_pairs = {
        '[': ']',
        '(': ')',
        '{': '}'
    };
    const open_tokens = Object.keys(maching_pairs);
    const brackets = Object.values(maching_pairs).concat(open_tokens);
    // we filter out what is not our matching characters
    const tokens = tokenize(str).filter(token => {
        return brackets.includes(token);
    });
    const stack = new Stack();
    for (const token of tokens) {
        if (open_tokens.includes(token)) {
            stack.push(token);
        } else if (!stack.is_empty()) {
             // there are matching characters on the stack
            const last = stack.top();
            // the last opening character needs to match
            // the closing bracket we have
            const closing_token = maching_pairs[last];
            if (token === closing_token) {
                stack.pop();
            } else {
                // the character don't match
                throw new Error(`Syntax error: missing closing ${closing_token}`);
            }
        } else {
            // this case when we have closing token but no opening one,
            // becauase the stack is empty
            throw new Error(`Syntax error: not matched closing ${token}`);
        }
    }
    return stack.is_empty();
}

The above code was implemented as part of my S-Expression parser, but the only thing I've used from that article is a function tokenize() that splits the string into tokens (where a token is a single object like number 123 or a string "hello"). If you want to process just the characters, you can use str.split(''), so the tokens would be an array of characters.

The code is much simpler than the S-Expression parser because we don't need to process all the tokens. But when we use the tokenize() function from the above article, we will be able to test input like this:

(this "))))")

The full source code (including the tokenize() function) can be found on GitHub.

Summary

You shouldn't even start processing expressions that have opening and closing characters with regular expressions. On StackOverflow there is this famous answer to this question:

RegEx match open tags except XHTML self-contained tags

Matching parentheses presents exactly the same problem, as parsing HTML. As you can see from the above code, ⁣it's a simpler problem to solve if we use the stack.

It's possible that we could write a Regular Expression that would check if the sequence of characters has matching parentheses. But it would soon get complicated if we had strings as tokens (sequence of characters), as with S-Expressions, and parentheses inside those stings should be ignored. It turns out that the solution is rather simple if we use the proper tools.

Personally, I love Regular Expressions, but you always need to decide if they're the right tool for the job.

NOTE: This article was based on an article in the Polish blog Głównie JavaScript (ang. Mostly JavaScript), with a title: Jak parować nawiasy lub inne znaki w
JavaScript?

If you like this article, you may want to follow me on Social Media: (Twitter/X and/or LinkedIn). You can also check my personal website and my new blog.

Instead, you can create a REST API directly in the browser without the need of any server. With this, you can showcase your skills in applications that interact with a backend hosted in places where you can't access the server side.

Note that if you search for "API without a server" you may find articles about serverless (which is still a kind of server). This article is completely different and showcases a relatively new browser API. Read on if you're interested.

Table of contents

• What is a Service Worker?

• How to register a Service Worker?

• How to create a basic HTTP response

• How to create a base project

  • Set up Vite

  • Use the Wayne library

  • Install the Service Worker

  • Test on the Web Server

• How to add React authentication

  • Create a JWT token

  • Add authentication API

  • Add authentication to React

• Next steps

• Fully working demo

What is a Service Worker?

The browser API that allows you to create pure in the browser HTTP responses to HTTP requests is called a Service Worker. This API was mostly created to intercept HTTP requests originated from the browser and serve them from cache.

This allows you to create applications called PWA that work when you don't have internet connection. So you can use them while on the train, where you may have unstable internet. When you're offline, the HTTP requests can be stored and sent to the real server when you get back online.

But this is not all what Service Workers can do. With them, you can create HTTP requests that never existed. It can intercept any HTTP requests, for example when you open an image in new tab or using AJAX (like with fetch API).

How to Register a Service Worker?

Service worker needs to be written in a separate file (often called sw.js, but you can name it whatever you want).

The location of that file is important. It should be located in the root of your app, often in the root of the domain.

To register a service worker, you need to execute this code:

if ('serviceWorker' in navigator) {
  var scope = location.pathname.replace(/\/[^\/]+$/, '/')
  navigator.serviceWorker.register('sw.js', { scope })
    .then(function(reg) {
       reg.addEventListener('updatefound', function() {
         var installingWorker = reg.installing;
         console.log('A new service worker is being installed:',
                     installingWorker);
       });
       // registration worked
       console.log('Registration succeeded. Scope is ' + reg.scope);
    }).catch(function(error) {
      // registration failed
      console.log('Registration failed with ' + error);
    });
}

This will install a service worker that can start to intercept HTTP requests.

NOTE: The service worker works only with HTTPS and localhost.

How to Create a Basic HTTP Response

The API of the Service Worker is very simple – you have an event called fetch
and you can respond to that event with any response:

self.addEventListener('fetch', event => {
    const url = new URL(event.request.url);
    if (url.pathname === '/api/hello/') {
        const headers = {
            'Content-Type': 'text/plain'
        };
        const msg = 'Hello, Service Worker!'
        event.respondWith(textResponse(msg, headers));
   }
});

function textResponse(string, headers) {
    const blob = new Blob([string], {
        type: 'text/plain'
    });
    return new Response(blob, { headers });
}

With this you code, you can open the URL /api/hello/ and it will display the text "Hello, Service Worker!" as a text file.

Also, one important thing: if you want to use the Service Worker immediately after it's installed, you need to add this code:

self.addEventListener('activate', (event) => {
  event.waitUntil(clients.claim());
});

Normally, the Service Worker intercepts requests only after you refresh the page. This code forces to accept requests immediately after installation.

NOTE: With service worker, you can also intercept request that are sent to different domains. If you have your app on GitHub pages, you can intercept the requests to any domain. Because there are no checks of the domain, this code:

await fetch('https://example.com/api/hello').then(res => res.text())

will also return Hello, Service Worker!.

How to Create a Base Project

You will create something more useful by creating a React project with very simple user authentication.

Note that this is not secure in any way, because user information and passwords will be visible in the code. But it can show that you know how to interact with an API in React.

Set Up Vite

First, you need to set up a simple React application with Vite.

To use Vite, you need to have Node.js installed. If you don't have it, you can read how to install it from this article.

Then, you need to run this command from the terminal:

npm create vite@latest

I've picked name auth, React, and JavaScript. This is the output I've got:

✔ Project name: … auth
✔ Select a framework: › React
✔ Select a variant: › JavaScript

Scaffolding project in /home/kuba/auth...

Done. Now run:

  cd auth
  npm install
  npm run dev

Next is to modify vite.config.js file, so Vite will know how to build the service worker file/

This is the config file Vite created:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
})

You need to modify the config file to include this code:

import { join } from "node:path";
import { buildSync } from "esbuild";

export default defineConfig({
  plugins: [
    react(),
    {
      apply: "build",
      enforce: "post",
      transformIndexHtml() {
        buildSync({
          minify: true,
          bundle: true,
          entryPoints: [join(process.cwd(), "src", "sw.js")],
          outfile: join(process.cwd(), "dist", "sw.js"),
        });
      },
    },
  ]
})

You need to include both imports and you can replace the existing config with the one above. You can also add the code in the curly braces into a plugin array.

Use the Wayne library

Then, you need to create a Service Worker file named sw.js. You will use Wayne library instead of writing the routes yourself. This will simplify the code.

First, you need to install Wayne:

npm install @jcubic/wayne

Then, you can create a file named sw.js (Note: you've put the "src" directory in the vite.config.js file, so you should save the file in that directory).

import { Wayne } from '@jcubic/wayne';

const app = new Wayne();

app.get('/api/hello/', (req, res) => {
   res.text('Hello, Service Worker!');
});

This code will work exactly the same as our previous example.

Install the Service Worker

Now, the last thing you need to do to set up your service worker is to register it. You could use the code that you saw earlier, but now you will use a library for this.

First, you need to install it:

npm install register-service-worker

And update src/main.jsx with this code:

import { register } from "register-service-worker";

register(`./sw.js`);

The last thing is to build the project by executing:

npm run build

NOTE: the dev mode will not work with the service worker – you need to build the project.

The instructions setting up a Service Worker with Vite were based on this article.

Test on the Web Server

To test your project you can use this command:

npx http-server -p 3000 ./dist/

This will create a simple HTTP server where you can test your application.

NOTE: if you open theindex.html file in a browser (like with drag and drop), the service worker will not work. This is because the file:// protocol has a lot of restrictions. That's why you need a web server.

If you test the app in the browser by opening the URL: http://127.0.0.1:3000, it will run the code that registers the service worker, and you will immediately be able to access our fake HTTP endpoint: http://127.0.0.1:3000/api/hello/. It should display the text:

Hello, Service Worker!

NOTE: to simplify testing, you can add "http-server -p 3000 ./dist/" to the package.json file into scripts:

"serve": "http-server -p 3000 ./dist/",

Remember that package.json is a JSON file, so you can't put a trailing comma if this will be the last script.

To make it work, you need to install the package:

npm install http-server

Now you can run the server with npm run serve.

NOTE: if you access the URL: http://127.0.0.1:3000/api/hello (you can read what is 127.0.0.1 in this article), you will get an error from http-server. This is because the route you created in the service worker used a trailing slash. To fix this, you can add a redirect:

app.get('/api/hello', (req, res) => {
   res.redirect(301, req.url + '/');
});

How to Add React Authentication

Now, after you have set up everything, you can add a real authentication endpoint and connect it with your React app.

Create a JWT token

We will use a popular JWT token for authentication. You can read more about them in this article.

First, you need to install a JWT library:

npm install jose

Then, you need to create a new file named jwt.js in the src directory:

import { SignJWT, jwtVerify } from 'jose';

const secret = new TextEncoder().encode(
  'cc7e0d44fd473002f1c42167459001140ec6389b7353f8088f4d9a95f2f596f2'
);

const alg = 'HS256';

const jwt = {
    sign: (payload) => {
        return new SignJWT(payload)
            .setProtectedHeader({ alg })
            .setIssuedAt()
            .setIssuer('https://freecodecamp.org')
            .setAudience('https://freecodecamp.org')
            .setExpirationTime('2h')
            .sign(secret)
    },
    verify: async (token) => {
        const { payload } = await jwtVerify(token, secret, {
            issuer: 'https://freecodecamp.org',
            audience: 'https://freecodecamp.org',
        });
        return payload;
    }
};

export default jwt;

This code is an ES Module that uses the jose JWT token library to create a new token, jwt.sign. It verifies that the token is correct with jwt.verify, and it also returns the payload, so you can extract anything you save in the token.

You can read more about the jose library from the documentation – the links to the docs are in the README.

NOTE: Because of the limitation of Service Worker, we can't create a proper real life authentication, where the access token is stored in a cookie (Service Worker don't allow creating cookies) and use refresh tokens to update the access token.

Add authentication API

Now, you can use the previous functions to create an API endpoint:

import jwt from './jwt';

app.post('/api/login', async (req, res) => {
    const { username, password } = await req.json() ?? {};
    if (username === 'demo' && password === 'demo') {
        const token = await jwt.sign({ username });
        res.json({ result: token });
    } else {
        res.json({ error: 'Invalid username or password' });
    }
});

This code will verify that the username and password are correct (both equal to "demo"), ⁣and create a new JWT token. If the username or password are not correct, it will return an error.

Add authentication to React

You created a React App with Vite, so you need to use JSX to add front-end authentication logic.

First, you create a helper function that will send an HTTP request to the /api/login endpoint with Fetch API:

function login(username, password) {
    return fetch('/api/login', {
        method: 'post',
        headers: {
            'Accept': 'application/json',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            username,
            password
        })
    }).then(res => res.json());
}

Next, you need to create a basic form:

<form>
  <div>
    <label for="user">username</label>
    <input id="user" />
  </div>
  <div>
    <label for="password">password</label>
    <input id="password" type="password" />
  </div>
  <button>login</button>
</form>

And a add bit of styling:

form {
  display: inline-flex;
  flex-direction: column;
  gap: 10px;
  align-items: flex-end;
}

label::after {
  content: ":";
}

label {
  width: 100px;
  display: inline-block;
  text-align: right;
  margin-right: 10px;
}

Next, you need an authentication function that you will add to an onSubmit event. ⁣
You will use two state variables for token and error:

function App() {
  const [token, setToken] = useState(null);
  const [error, setError] = useState(null);

  async function auth(event) {
    event.preventDefault();

    const res = await login(username, password);
    if (res.result) {
      setToken(res.result);
    } else if (res.error) {
      setError(res.error);
    }
  }

To get the username and password from the form you can use refs. You can also display the form only when the token is not set:

function App() {
  const [token, setToken] = useState(null);
  const [error, setError] = useState(null);
  const userRef = useRef();
  const passwordRef = useRef();

  async function auth(event) {
    event.preventDefault();
    const username = userRef.current.value;
    const username = passwordRef.current.value;

    const res = await login(username, password);
    if (res.result) {
      setToken(res.result);
    } else if (res.error) {
      setError(res.error);
    }
  }

  return (
    <div>
      <div className="card">
        {!token && (
          <form onSubmit={auth}>
            <div>
              <label for="user">username</label>
              <input id="user" ref={userRef}/>
            </div>
            <div>
              <label for="password">password</label>
              <input id="password" ref={passwordRef} type="password"/>
            </div>
            <button>login</button>
          </form>
        )}
        {error && <p className="error">{ error }</p>}
      </div>
    </div>
  );
}

Now you can test the App. If you type the username and password, they don't reset.

You can fix it by setting the ref value to an empty string at the end of the function:

userRef.current.value = '';
passwordRef.current.value = '';

There is another error. If you put a wrong username or password, you will get an error. But then, if you type the correct password, the error is not removed. To fix this issue, you need to reset the error state when setting the token:

  async function auth(event) {
    event.preventDefault();
    const username = userRef.current.value;
    const username = passwordRef.current.value;

    const res = await login(username, password);
    if (res.result) {
      setToken(res.result);
      setError(null);
    } else if (res.error) {
      setError(res.error);
    }
    userRef.current.value = '';
    passwordRef.current.value = '';
  }

Next thing that you can do is to extract the username from the token. This will also verify that the token is correct in your React app. You need to use the useEffect hook to run the code when the token changes:

import jwt from './jwt';

  // ...
  const [username, setUsername] = useState(null);

  useEffect(() => {
    jwt.verify(token).then(payload => {
      const { username } = payload;
      setUsername(username);
    }).catch(e => {
      setError(e.message);
    });
  }, [token]);

  // ...

If you run this code, you will get an error: Compact JWS must be a string or Uint8Array.

The reason is that the useEffect hook will be triggered when the token is null. Before you verify, you need to check if the token was set:

  useEffect(() => {
    if (token !== null) {
      jwt.verify(token).then(payload => {
        const { username } = payload;
        setUsername(username);
      }).catch(e => {
        setError(e.message);
      });
    }
  }, [token]);

Next, you can display the username after user login:

{token && (
  <div>
    <p>Welcome {username}</p>
  </div>
)}

Next Steps

The last thing we can do is to save the token in localStorage and add a logout button. But this is left as an exercise to the reader.

You can read about localStorage from this freeCodeCamp article.

You can improve this and add more endpoints, like getting real data that you will save in a sw.js file. You can store the data in IndexedDB, so it will be persistent like in in a real app. Read more about IndexedDB from this article.

IndexedDB doesn't have a very nice API, but there are libraries that add abstraction on top of it. My favorite is the SQL library AlaSQL, and idb by Jake Archibald.

Fully working demo

The full source code is available on GitHub in the repository jcubic/react-wayne-auth. You can test a working demo on GitHub pages.

If you like this article, you may want to follow me on Social Media: (Twitter/X and/or LinkedIn) and you an also check my personal website.

This article will show more advanced usage of the jQuery Terminal library. If you want something more basic, you can check this article: How to create interactive terminal like website with JavaScript that is written for more entry level programmers. You can also read it (or skim it) first before you begin reading this one.

Table of Contents

• What is the terminal and its history?

• What is jQuery Terminal?

• Base html file

• How to Initialize the Terminal

• Welcome message

• Line Gaps

• How to Add Colors to ASCII Art

  • Terminal Formatting

  • How to Use the Lolcat Library

  • Rainbow ASCII Art Greetings

  • How to Make the Greeting Text White

• How to Make Your First Command

• Default Commands

• How to Make Help Commands Executable

• Syntax Highlighting

• Tab Completion

• How to Add Shell Commands

• How to Improve Completion

• Typing Animation Command

• Credits Command

• Prefilled Commands

• Sharing Link to Terminal Session

• Working Terminal Portfolio Demo

• Adding Executables to Home Directory

• What Next?

• Share what you’ve created

What is the terminal and its history?

Terminals have a long history. It started as an upgrade from punch cards. Computers back in the day used teletypes, which was just a keyboard and a printer. You'd type on the keyboard, and the keystrokes would be sent to the computer (usually mainframe) and the output got printed on a printer.

Later on, the teletypes were replaced with terminals. A terminal was like the dump computer we see today. It was a CRT Monitor with a keyboard. So instead of getting the output on the printer, it would be displayed on the monitor.

Today we still use this type of interface (the Command Line) to talk with computers.

The command line is a terminal emulator and is a big part of Unix systems, like GNU/Linux or MacOS. On Windows, you have PowerShell or cmd.exe file that allows you to type commands and get responses in the form of text. You can also install GNU/Linux system on Windows in the form of WSL. CLI interfaces are used mostly by power users, developers, and system administrators.

If you're new to the command line, you can read this article: Command Line for Beginners – How to Use the Terminal Like a Pro [Full Handbook].

What is jQuery Terminal?

jQuery Terminal is a JavaScript library. It's a plugin for the jQuery library. jQuery Terminal is more like a framework that has jQuery as its dependency. We'll mostly use JavaScript and very little jQuery in this article.

Let's create our terminal-based portfolio using jQuery Terminal.

Base HTML file

The first thing you need to do is to include jQuery and jQuery Terminal library in your project.

This is a basic HTML file:

<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/jquery.terminal/css/jquery.terminal.min.css"/>
</head>
<body>
<script src="https://cdn.jsdelivr.net/npm/jquery"></script>
<script src="https://cdn.jsdelivr.net/npm/jquery.terminal/js/jquery.terminal.min.js"></script>
<script src="my-terminal.js"></script>
</body>
</html>

Then inside the my-terminal.js file, we will write our code in JavaScript.

How to Initialize the Terminal

To create a basic terminal, you need to put in this code:

const commands = {};

const term = $('body').terminal(commands);

The string 'body' indicates the CSS selector where terminal should be created. Here we use 'body' so the terminal will be the only thing on the page. But it doesn't have to be full screen. You can create a website where the terminal is only part of the page, like in a window that looks like part of the Operating System.

The first argument to the terminal method is called an interpreter. It's a way to add your commands. An object is the simplest way to create them. See creating the interpreter to learn more.

If the terminal font is too small, you can make it a little bit bigger with CSS custom properties (also known as CSS variables):

:root {
    --size: 1.2;
}

Welcome Message

The first thing we need to do is to get rid of the default greeting message and replace it with nice-looking custom ASCII Art. We will use the Filget library written in JavaScript to do this.

There are a few Figlet libraries on npm. We will use a package named figlet.

The first thing you should do is pick the right font. Go to figlet playground and write the text you want for your greeting. We will use "Terminal Portfolio" and click "Test All". It should display your text with all the fonts. Scroll through the list and pick the font you like.

I picked a font "slant" that looks like this:

You can copy this text and put into a string, but you will have issues like with the backslash that needs to be escaped using quote characters.

const greetings = `  ______                    _             __   ____             __  ____      ___     
 /_  __/__  _________ ___  (_)___  ____ _/ /  / __ \\____  _____/ /_/ __/___  / (_)___ 
  / / / _ \\/ ___/ __ \`__ \\/ / __ \\/ __ \`/ /  / /_/ / __ \\/ ___/ __/ /_/ __ \\/ / / __ \\
 / / /  __/ /  / / / / / / / / / / /_/ / /  / ____/ /_/ / /  / /_/ __/ /_/ / / / /_/ /
/_/  \\___/_/  /_/ /_/ /_/_/_/ /_/\\__,_/_/  /_/    \\____/_/   \\__/_/  \\____/_/_/\\____/`

const term = $('body').terminal(commands, {
    greetings
});

NOTE: The second argument to the jQuery Terminal is an object with options – we used a single option greetings.

This doesn't look good and it's hard to modify. Also, if you create the greeting by hardcoding a string, it may get distorted on smaller screens. That's why we will use the figlet library in JavaScript.

First, we need to include the figlet library in HTML:

<script src="https://cdn.jsdelivr.net/npm/figlet/lib/figlet.js"></script>

To initialize the library in JavaScript, we need to load the fonts:

const font = 'Slant';

figlet.defaults({ fontPath: 'https://unpkg.com/figlet/fonts/' });
figlet.preloadFonts([font], ready);

This code will load the 'Slant' font and call the function ready when the font is loaded.

So we need to write this function:

function ready() {

}

Now we can do two things, we can put the initialization of jQuery Terminal inside that function:

let term;

function ready() {
   term =  $('body').terminal(commands, {
      greetings
   });
}

With this, we can use the greeting option. But we can also use the echo method to render the greeting, and when initializing the terminal we will put null or false as a greetings to disable the default one:

const term = $('body').terminal(commands, {
    greetings: false
});

function ready() {
   term.echo(greetings);
}

This will work better because the library will initialize the terminal immediately and will not need to wait for loading the fonts.

Note that we still need to define the greetings using figlet. To do this we can write this function:

function render(text) {
    const cols = term.cols();
    return figlet.textSync(text, {
        font: font,
        width: cols,
        whitespaceBreak: true
    });
}

This function uses the figlet::textSync() method to return a string and use terminal::cols(), to get the number of characters per line. With this, we can make our text responsive.

This function can be used inside ready.

function ready() {
   term.echo(render('Terminal Portfolio'));
}

This will create a string and pass it to the echo method. But this will be the same as with:

term.echo(greeting);

And our hard-coded greetings. So if you resize the terminal, the greetings can still get distorted. To make the text responsive, you need to echo a function. This function will be called on each re-render of the terminal, which will happen when you resize the page.

We can use the arrow function for this:

function ready() {
   term.echo(() => render('Terminal Portfolio'));
}

If you want to add some text below the ASCII art, you can do this by concatenating the string after render:

function ready() {
   term.echo(() => {
     const ascii = render('Terminal Portfolio');
     return `${ascii}\nWelcome to my Terminal Portfolio\n`;
   });
}

NOTE: If you run this code, you will notice that there is an empty line after the ASCII art. This is because the figlet library adds some spaces after the text.

To get rid of this, you can use string::replace() with a regular expression that will remove all spaces and newlines from the end.

We can't use string::trim(), because we don't want to remove the leading lines:

function render(text) {
    const cols = term.cols();
    return trim(figlet.textSync(text, {
        font: font,
        width: cols,
        whitespaceBreak: true
    }));
}

function trim(str) {
    return str.replace(/[\n\s]+$/, '');
}

You can also pause the terminal when it loads the fonts:

const term = $('body').terminal(commands, {
    greetings: false
});

term.pause();

function ready() {
   term.echo(() => render('Terminal Portfolio')).resume();
}

You can can chain terminal methods, the same as with jQuery.

Line Gaps

If the font you pick creates gaps between the lines, like in this image with font ANSI Shadow:

You can remove the gaps by adding the ansi option set to true. The option was added specifically to fix an issue with displaying ANSI Art.

term.echo(() => render('Terminal Portfolio'), { ansi: true });

The above ASCII Art will look like this:

How to Add Colors to ASCII Art

You can spice up your ASCII Art by using a library called lolcat. lolcat is a Linux command that can style text in the terminal with rainbow colors. There is also a library called isomorphic-lolcat, that you can use in JavaScript to make your ASCII Art in rainbow colors.

Terminal Formatting

To use the lolcat library, you first need to know how to change the colors of the terminal.

You can do this using low-level formatting that looks like this:

[[b;red;]some text]

The whole text is wrapped in brackets and the formatting of the text is in additional brackets, where each argument is separated by a semicolon. To learn more about the syntax, you can read the Wiki Article: Formatting and Syntax Highlighting.

Here, we'll only use a basic change of color. Instead of red, you can use CSS color names, hex color, or rgb().

How to Use the Lolcat Library

To use the library, we first need to include it in HTML:

<script src="https://cdn.jsdelivr.net/npm/isomorphic-lolcat"></script>

To format the string with colors, we can use this function:

function rainbow(string) {
    return lolcat.rainbow(function(char, color) {
        char = $.terminal.escape_brackets(char);
        return `[[;${hex(color)};]${char}]`;
    }, string).join('\n');
}

function hex(color) {
    return '#' + [color.red, color.green, color.blue].map(n => {
        return n.toString(16).padStart(2, '0');
    }).join('');
}

The lolcat.rainbow will call a function in every character from the input string, and pass color as an object with RGB values and the character.

Rainbow ASCII Art Greetings

To use this code, you need to wrap the call to render with rainbow:

function ready() {
   term.echo(() => {
     const ascii = rainbow(render('Terminal Portfolio'));
     return `${ascii}\nWelcome to my Terminal Portfolio\n`;
   }).resume();
}

You can also use two calls to echo, since only the Figlet message needs to be executed inside the function:

function ready() {
   term.echo(() => rainbow(render('Terminal Portfolio')))
       .echo('Welcome to my Terminal Portfolio\n').resume();
}

You'll notice that when you resize the window, the rainbow changes randomly. This is the default behavior of lolcat. To change it, you need to set the random seed.

function rand(max) {
    return Math.floor(Math.random() * (max + 1));
}

function ready() {
   const seed = rand(256);
   term.echo(() => rainbow(render('Terminal Portfolio'), seed))
       .echo('Welcome to my Terminal Portfolio\n').resume();
}

function rainbow(string, seed) {
    return lolcat.rainbow(function(char, color) {
        char = $.terminal.escape_brackets(char);
        return `[[;${hex(color)};]${char}]`;
    }, string, seed).join('\n');
}

The rand function returns a pseudo-random number from 0 to max value. Here we created a random value from 0 to 256.

How to Make the Greeting Text White

As we showed previously, you can make the text white with terminal formatting. You can use:

• [[;white;]Welcome to my Terminal Portfolio]

• [[;#fff;]Welcome to my Terminal Portfolio]

• [[;rgb(255,255,255);]Welcome to my Terminal Portfolio]

Moreover, if you include additional file XML formatting, you can use XML-like syntax. That makes formatting much easier.

<script src="https://cdn.jsdelivr.net/npm/jquery.terminal/js/xml_formatting.js"></script>

After including the above file in HTML, you can use CSS named colors as XML tags:

<white>Welcome to my Terminal Portfolio</white>

The XML formatting supports more tags like links and images. See Extension XML Formatter for more info.

NOTE: XML formatter is a function added to $.terminal.defaults.formatters, which transforms the input XML-like text into terminal formatting. You can add the same to your own formatters.

How to Make Your First Command

After the greeting, we can write our first command. It will be helpful and will work with any commands we add later.

const commanns = {
    help() {

    }
};

This will be our help command where we'll add a list of commands available to our terminal portfolio. We will use Intl.ListFormat, which creates a list of elements with and before the last element.

const formatter = new Intl.ListFormat('en', {
  style: 'long',
  type: 'conjunction',
});

To create a list, we need to use formatter.format() and pass an array of commands. To get that array we can use Object.keys():

const commands = {
    help() {
        term.echo(`List of available commands: ${help}`);
    }
};

const command_list = Object.keys(commands);
const help = formatter.format(command_list);

When you type help you should see:

List of available commands: help

You also need to add the echo command:

const commands = {
    help() {
        term.echo(`List of available commands: ${help}`);
    },
    echo(...args) {
        term.echo(args.join(' '));
    }
};

Now the help command works:

List of available commands: help and echo

But if you try to execute 'echo hello' you will get an error:

[Arity] Wrong number of arguments. The function 'echo' expects 0 got 1!

By default, jQuery Terminal checks the number of arguments and the number of parameters the function accepts. The problem is that the rest operator makes all arguments optional and the length function property is 0. To fix the issue we need to disable the Arity check with an option:

const term = $('body').terminal(commands, {
    greetings: false,
    checkArity: false
});

Now the echo commands should work.

Default Commands

By default, the jQuery Terminal has two default commands:

• clear: this command clears everything on the terminal.

• exit: this command exits from nested interpreters.

You can disable them by passing the name to the option and setting it to false. Since we won't use nested interpreters, we can disable exit:

const term = $('body').terminal(commands, {
    greetings: false,
    checkArity: false,
    exit: false
});

But clear can be useful. So we can add it to the list of commands:

const command_list = ['clear'].concat(Object.keys(commands));

How to Make Help Commands Executable

We can make the UX better to allow clicking on the command and execute it just like when the user types it.

We will need a few things to do this. First, we need to add formatting to each command and add an HTML class attribute. We can also make the command white so it's more visible.

const command_list = Object.keys(commands);
const formatted_list = command_list.map(cmd => {
    return `<white class="command">${cmd}</white>`;
});
const help = formatter.format(formatted_list);

Next is to add affordance. To indicate that the user can click the command, we need to change the cursor in CSS:

.command {
    cursor: pointer;
}

The last step is to execute the command when the user clicks the command. We need to add an event handler with jQuery (jQuery Terminal dependency) or we can use the native browser addEventListener. Here we use jQuery:

term.on('click', '.command', function() {
   const command = $(this).text();
   term.exec(command);
});

terminal::exec() is a way to execute a command programmatically, just like user would type it and press enter.

You can test it by typing help and clicking help again.

Clicking echo will print an empty line. We can fix it by checking if the array of arguments is not empty, before executing terminal::echo():

const commands = {
    echo(...args) {
        if (args.length > 0) {
            term.echo(args.join(' '));
        }
    }
};

Now clicking on echo will only show the executed command.

NOTE: If for any reason you don't want to show the prompt and the command that has been executed, you can silence the exec by passing true as the second argument.

term.exec('help', true);

Syntax Highlighting

As we discussed earlier, we can use custom syntax highlighting of our shell by pushing a function into $.terminal.defaults.formatters.We can also use the $.terminal.new_formatter helper function.

Let's make our commands white as we type them. The formatter can be an array (of regex and replacement), or a function. We have a fixed number of commands and we only want to make those that are on the list white. We can do this by adding a regular expression:

const any_command_re = new RegExp(`^\s*(${command_list.join('|')})`);

This regular expression will check if, at the beginning of the string, there is an optional whitespace and one of the commands. Right now the regex will look like this: /^\s*(help|echo)/. This is how to create new formatter:

$.terminal.new_formatter([any_command_re, '<white>$1</white>']);

If you would like to make command arguments in different colors, you'll need a function, where you will use String::replace().

const re = new RegExp(`^\s*(${command_list.join('|')}) (.*)`);

$.terminal.new_formatter(function(string) {
    return string.replace(re, function(_, command, args) {
        return `<white>${command}</white> <aqua>${args}</aqua>`;
    });
});

This is just an example of using String::replace. If you have just one replacement, you can use an array. This will be the same:

const re = new RegExp(`^\s*(${command_list.join('|')})(\s?.*)`);

$.terminal.new_formatter([re, function(_, command, args) {
    return `<white>${command}</white><aqua>${args}</aqua>`;
}]);

NOTE: If you add the class <white class="command"> to the formatter, you will be able to click on the typed command to execute it again.

Tab Completion

Another feature we can add is to complete the command when you press the tab key. This is super easy – we only need to add the completion option set to true:

const term = $('body').terminal(commands, {
    greetings: false,
    checkArity: false,
    exit: false,
    completion: true
});

Now when you type h and press tab, it will complete the command help for you.

How to Add Shell Commands

Now we can add the most important commands that allow us to navigate through the portfolio. We will implement directories as the main entry point so the user will need to type the ls command to see a list of things, cd into that directory, and ls again to see the contents.

const directories = {
    education: [
        '',
        '<white>education</white>',

        '* <a href="https://en.wikipedia.org/wiki/Kielce_University_of_Technology">Kielce University of Technology</a> <yellow>"Computer Science"</yellow> 2002-2007 / 2011-2014',
        '* <a href="https://pl.wikipedia.org/wiki/Szko%C5%82a_policealna">Post-secondary</a> Electronic School <yellow>"Computer Systems"</yellow> 2000-2002',
        '* Electronic <a href="https://en.wikipedia.org/wiki/Technikum_(Polish_education)">Technikum</a> with major <yellow>"RTV"</yellow> 1995-2000',
        ''
    ],
    projects: [
        '',
        '<white>Open Source projects</white>',
        [
            ['jQuery Terminal',
             'https://terminal.jcubic.pl',
             'library that adds terminal interface to websites'
            ],
            ['LIPS Scheme',
             'https://lips.js.org',
             'Scheme implementation in JavaScript'
            ],
            ['Sysend.js',
             'https://jcu.bi/sysend',
             'Communication between open tabs'
            ],
            ['Wayne',
             'https://jcu.bi/wayne',
             'Pure in browser HTTP requests'
            ],
        ].map(([name, url, description = '']) => {
            return `* <a href="${url}">${name}</a> &mdash; <white>${description}</white>`;
        }),
        ''
    ].flat(),
    skills: [
        '',
        '<white>languages</white>',

        [
            'JavaScript',
            'TypeScript',
            'Python',
            'SQL',
            'PHP',
            'Bash'
        ].map(lang => `* <yellow>${lang}</yellow>`),
        '',
        '<white>libraries</white>',
        [
            'React.js',
            'Redux',
            'Jest',
        ].map(lib => `* <green>${lib}</green>`),
        '',
        '<white>tools</white>',
        [
            'Docker',
            'git',
            'GNU/Linux'
        ].map(lib => `* <blue>${lib}</blue>`),
        ''
    ].flat()
};

This is our basic structure. You can edit it and add your own information. First, we will add a cd command that changes the directory.

const root = '~';
let cwd = root;

const commands = {
    cd(dir = null) {
        if (dir === null || (dir === '..' && cwd !== root)) {
            cwd = root;
        } else if (dir.startsWith('~/') && dirs.includes(dir.substring(2))) {
            cwd = dir;
        } else if (dir.startsWith('../') && cwd !== root &&
                   dirs.includes(dir.substring(3))) {
            cwd = root + '/' + dir.substring(3);
        } else if (dirs.includes(dir)) {
            cwd = root + '/' + dir;
        } else {
            this.error('Wrong directory');
        }
    }
};

This will handle all the cases of changing the directory. Next is to add a prompt.

To see what directory we are in, we need to add a custom prompt. We can create a function as a prompt option:

const user = 'guest';
const server = 'freecodecamp.org';

function prompt() {
    return `<green>${user}@${server}</green>:<blue>${cwd}</blue>$ `;
}

And use it as an option:

const term = $('body').terminal(commands, {
    greetings: false,
    checkArity: false,
    completion: true,
    exit: false,
    prompt
});

The green color don't look very good, so we can use a color from Ubuntu to make the terminal look more real. We can overwrite the default XML color tags like this:

$.terminal.xml_formatter.tags.green = () => {
    return `[[;#44D544;]`;
};

Next is the ls command.

function print_home() {
     term.echo(dirs.map(dir => {
         return `<blue class="directory">${dir}</blue>`;
     }).join('\n'));
}

const commands = {
    ls(dir = null) {
        if (dir) {
            if (dir.match(/^~\/?$/)) {
                // ls ~ or ls ~/
                print_home();
            } else if (dir.startsWith('~/')) {
                const path = dir.substring(2);
                const dirs = path.split('/');
                if (dirs.length > 1) {
                    this.error('Invalid directory');
                } else {
                    const dir = dirs[0];
                    this.echo(directories[dir].join('\n'));
                }
            } else if (cwd === root) {
                if (dir in directories) {
                    this.echo(directories[dir].join('\n'));
                } else {
                    this.error('Invalid directory');
                }
            } else if (dir === '..') {
                print_home();
            } else {
                this.error('Invalid directory');
            }
        } else if (cwd === root) {
            print_home();
        } else {
            const dir = cwd.substring(2);
            this.echo(directories[dir].join('\n'));
        }
    }
};

Similar to the green we had before, the blue color is not that great. So we can use the color from Ubuntu again. To do this, we need to use the same custom XML tags for the color blue:

$.terminal.xml_formatter.tags.blue = (attrs) => {
    return `[[;#55F;;${attrs.class}]`;
};

We added the HTML class for a reason. Let's change directory when the user clicks the directory. Just like we did with commands, we can invoke the cd command the same way as as a user would type it.

term.on('click', '.directory', function() {
    const dir = $(this).text();
    term.exec(`cd ~/${dir}`);
});

NOTE: if you have long command and want to get the text for that command, it's better to use: $(this).data('text'). When the single formatting is wrapped (when text is longer than the width of the terminal) the .text() will no longer have full text, but the full text is always in the data-text HTML attribute.

We also need to update our CSS to change the cursor:

.command, .directory {
    cursor: pointer;
}

How to Improve Completion

Our completion is not perfect as it only completes the commands. If you'd like to have completion that also handles directories, you need to use a function:

const term = $('body').terminal(commands, {
    greetings: false,
    checkArity: false,
    completion(string) {
        // in every function we can use `this` to reference term object
        const cmd = this.get_command();
        // we process the command to extract the command name
        // and the rest of the command (the arguments as one string)
        const { name, rest } = $.terminal.parse_command(cmd);
        if (['cd', 'ls'].includes(name)) {
            if (rest.startsWith('~/')) {
                return dirs.map(dir => `~/${dir}`);
            }
            if (rest.startsWith('../') && cwd != root) {
                return dirs.map(dir => `../${dir}`);
            }
            if (cwd === root) {
                return dirs;
            }
        }
        return Object.keys(commands);
    },
    prompt
});

NOTE: The string argument was left as documentation. It can be used if you only want to complete a single word.

Typing Animation Command

Another command that we will add is an animated joke. We will print random jokes using an API that looks like the user typing.

We will use the Joke API for this purpose.

The API returns JSON with two types of responses: twopart and a single. This is the code that prints the text on the terminal:

// we use programming jokes so it fit better
// developer portfolio
const url = 'https://v2.jokeapi.dev/joke/Programming';
const commands = {
    async joke() {
        const res = await fetch(url);
        const data = await res.json();
        if (data.type == 'twopart') {
            // as said before in every function, passed directly
            // to the terminal, you can use `this` object
            // to reference terminal instance
            this.echo(`Q: ${data.setup}`);
            this.echo(`A: ${data.delivery}`);
        } else if (data.type === 'single') {
            this.echo(data.joke);
        }
    },
}

To add typing animation, you need to add an option to the echo method:

this.echo(data.joke, { delay: 50, typing: true });

There is one caveat: if you have a sequence of typing animations, you need to await for the previous one to finish (the echo will return a promise when animating). When creating such animation you can wrap your code with animation method:

// we use programming jokes so it fits better
// developer portfolio
const url = 'https://v2.jokeapi.dev/joke/Programming';
const commands = {
    async joke() {
        const res = await fetch(url);
        const data = await res.json();
        if (data.type == 'twopart') {
            // this method allow to create sequence of animations
            this.animation(async () => {
                // as said before in every function, passed 
                // directly to terminal, you can use `this` object
                // to reference terminal instance
                // and since we use arrow function we reference
                // this from joke function/command
                await this.echo(`Q: ${data.setup}`, {
                    delay: 50,
                    typing: true
                });
                await this.echo(`A: ${data.delivery}`, {
                    delay: 50,
                    typing: true
                });
            });
        } else if (data.type === 'single') {
            this.echo(data.joke, {
                delay: 50,
                typing: true
            });
        }
    }
};

You can read more about typing animation in this article: Typing Animation.

Credits Command

The last command we will add is a credits command where we will list the JavaScript libraries we used:

const commands = {
    credits() {
        return [
            '',
            '<white>Used libraries:</white>',
            '* <a href="https://terminal.jcubic.pl">jQuery Terminal</a>',
            '* <a href="https://github.com/patorjk/figlet.js/">Figlet.js</a>',
            '* <a href="https://github.com/jcubic/isomorphic-lolcat">Isomorphic Lolcat</a>',
            '* <a href="https://jokeapi.dev/">Joke API</a>',
            ''
        ].join('\n');
    }
};

This is an example of another way to print something on the terminal – if you return something from a function it will be printed. You can also return a Promise, so you can send an AJAX request to the server and print the results.

Prefilled Commands

You can make it easier for users to know what to do with the terminal, especially if they are not that familiar with Unix. You can do this by executing example commands:

term.exec(command)

You can also use animation with exec:

term.exec(command, { typing: true, delay: 50 });

Sharing Link to Terminal Session

Another cool thing that I will show you is recording commands in the URL. You can create whole terminal session and save it in a URL hash. To start recoding a session you need to execute the following:

term.history_state(true);

When you execute the command echo x, it should create a URL hash that looks like this: #[[0,1,"echo%20x"]].

To stop recording, you can use:

term.history_state(false);

You can write this into a command record start | stop, so it will be easier to record sessions.

The last thing to do to restore the session is to use the option execHash: true.

const term = $('body').terminal(commands, {
    /* rest of the options */
    execHash: true
});

When you do this and refresh the page, while having the URL hash with the session, it should replay the session and you should see same output as you did when you recorded it.

If you want the exec to be animated you can use this option:

const term = $('body').terminal(commands, {
    /* rest of the options */
    execHash: true,
    execAnimation: true
});

To share the link, it’s better to use a URL shortener like TinyURL. Make sure you test the shortened URL to see if it works.

How to Add Executables to the Home Directory

Another thing you can do to improve the portfolio is to help your visitor learn what commands they can use, by introducing executable when running ls. They will look like binaries on the Linux system.

// not every command needs to be binary
// we picked those three that works more like real programs
const files = [
    'joke',
    'credits',
    'record'
];

function print_home() {
     term.echo(dirs.map(dir => {
         return `<blue class="directory">${dir}</blue>`;
     }).join('\n'));
     term.echo(files.map(file => {
         return `<green class="command">${file}</green>`;
     }).join('\n'));
}

With this, you will be able to click the command and execute it. So your visitors will know that they can run joke command without the need to type help command. For this to work, we need one last change, adding class to the green XML tag:

$.terminal.xml_formatter.tags.green = (attrs) => {
    return `[[;#44D544;;${attrs.class}]`;
};

Working Terminal Portfolio Demo

Here is a fully working Demo of our Interactive Terminal Portfolio Website.

What Next?

You can add a lot of commands to this portfolio. The only limitation is your imagination.

You can check these examples for inspiration:

• CodePen Collection with jQuery Terminal Demos.

• Retro (Vintage) Terminal CodePen Demo.

• jQuery Terminal Examples Page.

• Terminal 404 Error Page.

• Fake GNU/Linux Terminal.

If you have an idea that is not listed here, you can ask on StackOverflow with jquery-terminal tag. If you have something more time consuming, you can also ask for paid support.

Share what you’ve created

If you create a cool terminal portfolio, you can share it and tag me on Twitter. I would love to take a look. Especially if you create something more than what’s included in the tutorial. You can also share on a terminal chat on my website (it’s a similar terminal portfolio, but with chat).

Lisp is the easiest language for implementation, and creating a parser is the first step. We can use a parser generator for this, but it's easier to write the parser yourself. We'll use JavaScript.

What are S-expressions?

If you're not familiar with the Lisp language, S-expressions look like this:

(+ (second (list "xxx" 10)) 20)

This is a data format, where everything is created from atoms or lists surrounded with parenthesis (where atoms of other lists are separated by spaces).

S-expressions can have different data types, just like JSON:

• numbers
• strings
• symbols – which are like strings but without quotes – can be interpreted
  as variable names from different languages.

Additionally, you can use a special dot operator that creates a pair.

(1 . b)

You can represent a list as doted pairs (which indicates that they are in fact a linked list data structure).

This list:

(1 2 3 4)

Can be written as:

(1 . (2 . (3 . (4 . nil))))

nil is the special symbol that indicates the end of the list of an empty list. With this format, you can create any binary tree. But we'll not use this doted notation in our parser so we don't complicate things.

What are S-expressions Used For?

Lisp code is created from S-expressions, but you can also use it as a data exchange format.

They are also part of text representation of WebAssembly. Probably because of the simplicity of the parser, and that you don't need to come up with your format. You can use them for the communication between server and browser, instead of JSON.

How to Implement S-expression Parser in JavaScript

Tokenizer

The tokenizer is part of the parser that splits the text into tokens that then can be parsed.

Usually, a parser is accompanied by Lexer or a tokenizer that generates the tokens.
This is how some parser generators work (like lex and Yacc or flex and bison. The second one is the free and open source software, part of the GNU project).

The simplest way of tokenizing is to use regular expressions. If you're not familiar with regular expressions (or Regex for short) you can read this article:
A Practical Guide to Regular Expressions – Learn Regex with Real Life Examples.

This is the simplest way of tokenization:

'(foo bar (baz))'.split(/(\(|\)|\n|\s+|\S+)/);

This is a union (with a pipe operator) or different cases we need to handle. Parentheses are special characters in Regex, so they need to be escaped by a slash.

It almost works. The first problem is that there are empty strings between the regex matching. Like this expression:

'(('.split(/(\(|\)|\n|\s+|\S+)/);
// ==> [ '', '(', '', '(', '' ]

We have 5 tokens instead of 2. We can solve this problem with an Array::filter.

'(('.split(/(\(|\)|\n|\s+|\S+)/).filter(token => token.length);
// ==> ["(", "("]

If the token is empty, the length will return 0 and will be converted to false, which means that it will filter out all empty strings.

We'll also not need spaces, so we can also filter them out:

'(   ('.split(/(\(|\)|\n|\s+|\S+)/).filter(token => token.trim().length);
// ==> ["(", "("]

The second bigger problem is with baz)) as the last token, here is an example:

'(foo bar (baz))'.split(/(\(|\)|\n|\s+|\S+)/).filter(token => token.trim().length);
// ==> ["(", "foo", "bar", "(", "baz))"]

The problem is the expression \S+, which is greedy and matches everything that is not a space. To fix the problem, we can use this expression: [^\s()]+.

It will match everything that is not a space and not a parentheses (same as \S+ but
with parentheses).

(foo bar (baz))'.split(/(\(|\)|\n|\s+|[^\s()]+)/).filter(token => token.trim().length);
// ==> ["(", "foo", "bar", "(", "baz", ")", ")"]

As you can see, the output is correct. Let's write this tokenizer as a function:

const tokens_re = /(\(|\)|\n|\s+|[^\s()]+)/;
function tokenize(string) {
    string = string.trim();
    if (!string.length) {
        return [];
    }
    return string.split(tokens_re).filter(token => token.trim());
}

We don't need to use length after token.trim() because an empty string is also converted to false value and the filter will remove those values.

But what about string expressions (those in quotes)? Let's see what will happen:

tokenize(`(define (square x)
            "Function calculate square of a number"
            (* x x))`);
// ==> ["(", "define", "(", "square", "x", ")", "\"Function", "calculate", "square",
// ==>  "of", "a", "number\"", "(", "*", "x", "x", ")", ")"]

NOTE: This is a function in the Scheme dialect of Lisp. We used template literals so we could add newline characters inside the Lisp code.

As you can see from the output, the single stings are all split by spaces. Let's fix that:

Regular Expressions for Strings

We need to add string literals as an exception to our tokenizer. The best is the first item in the union in our regex.

The expression that handles string literals looks like this:

/"[^"\\]*(?:\\[\S\s][^"\\]*)*"/

It handles escaped quotes inside a string.

This is how the full regular expression should look like:

const tokens_re = /("[^"\\]*(?:\\[\S\s][^"\\]*)*"|\(|\)|\n|\s+|[^\s()]+)/;

NOTE: We can also add Lisp comments, but because this is not a Lisp parser but S-expression,⁣ we'll not do that here. JSON doesn't support comments as well. If you want to create a Lisp parser, you can add them as an exercise.

Our tokenizer now works correctly:

tokenize(`(define (square x)
            "Function calculate square of a number"
            (* x x))`);
// ==> ["(", "define", "(", "square", "x", ")",
// ==>  "\"Function calculate square of a number\"",
// ==>  "(", "*", "x", "x", ")", ")"]

Parser

We'll create our parser using a stack data structure (LIFO - Last In First Out).

To fully understand how the parser works, it is good to know about data structures, like linked lists, binary trees, and stacks.

Here is the first version of our parser:

function parse(string) {
    const tokens = tokenize(string);
    const result = []; // as normal array
    const stack = []; // as stack
    tokens.forEach(token => {
        if (token == '(') {
            stack.push([]); // add new list to stack
        } else if (token == ')') {
            if (stack.length) {
                // top of the stack is already constructed list
                const top = stack.pop();
                if (stack.length) {
                    // add constructed list to previous list
                    var last = stack[stack.length - 1];
                    last.push(top);
                } else {
                    result.push(top); // fully constructed list
                }
            } else {
                throw new Error('Syntax Error - unmached closing paren');
            }
        } else {
            // found atom add to the top of the stack
            // top is used as an array we only add at the end
            const top = stack[stack.length - 1];
            top.push(token);
        }
    });
    if (stack.length) {
        throw new Error('Syntax Error - expecting closing paren');
    }
    return result;
}

The function returns an array of our structures in the form of arrays. If we need to parse more than one S-expressions, we will have more items in an array:

parse(`(1 2 3) (1 2 3)`)
// ==> [["1", "2", "3"], ["1", "2", "3"]]

Although we don't need to handle dots, S-expressions can be in this form:

((foo . 10) (bar . 20))

We don't need to create a special structure for our lists to have a working parser. But it's a good idea to have this structure from the beginning (so you can use this as a base for a Lisp interpreter). We will use a Pair class, so we'll be able to create any binary tree.

class Pair {
    constructor(head, tail) {
        this.head = head;
        this.tail = tail;
    }
}

We will also need something that will represent the end of the list (or an empty list). In Lisp language, it's usually nil:

class Nil {}
const nil = new Nil();

We can create a static method that will convert an array into our structure:

class Pair {
    constructor(head, tail) {
        this.head = head;
        this.tail = tail;
    }
    static fromArray(array) {
        if (!array.length) {
            return nil;
        }
        let [head, ...rest] = array
        if (head instanceof Array) {
            head = Pair.fromArray(head);
        }
        return new Pair(head, Pair.fromArray(rest));
    }
}

To add this to our parser, all we have to do is to add it at the end:

result.map(Pair.fromArray);

NOTE: If you would like to add a dot operator later, you will need to create pairs by hand, inside the parser.

We didn't convert the whole array because this will be the container for our S-expressions. Each element in an array should be a list, that's why we used Array::map.

Let's see how it works:

parse('(1 (1 2 3))')

The output will be a structure like this (this is the output of JSON.stringify with inserted value of nil).

{
    "head": "1",
    "tail": {
        "head": {
            "head": "1",
            "tail": {
                "head": "2",
                "tail": {
                    "head": "3",
                    "tail": nil
                }
            }
        },
        "tail": nil
    }
}

The last thing that we can add is to stringify the List, by adding a toString method to our Pair class:

class Pair {
    constructor(head, tail) {
        this.head = head;
        this.tail = tail;
    }
    toString() {
        const arr = ['('];
        if (this.head) {
            const value = this.head.toString();
            arr.push(value);
            if (this.tail instanceof Pair) {
                // replace hack for the nested list
                // because the structure is a tree
                // and here tail is next element
                const tail = this.tail.toString().replace(/^\(|\)$/g, '');
                arr.push(' ');
                arr.push(tail);
            }
        }
        arr.push(')');
        return arr.join('');
    }
    static fromArray(array) {
        // ... same as before
    }
}

Let's see how it works:

parse("(1 (1 2 (3)))")[0].toString()
// ==> "(1 (1 2 (3)))"

The last problem is that the output structure doesn't have numbers. Everything is a string.

Parsing of Atoms

We'll use the regular expressions below:

const int_re = /^[-+]?[0-9]+([eE][-+]?[0-9]+)?$/;
const float_re = /^([-+]?((\.[0-9]+|[0-9]+\.[0-9]+)([eE][-+]?[0-9]+)?)|[0-9]+\.)$/;
if (atom.match(int_re) || atom.match(float_re)) {
    // in javascript every number is float but if it's slow you can use parseInt for int_re
    return parseFloat(atom);
}

Next, we can parse strings. Our strings are almost the same as those in JSON, the only difference is that they can have newlines (this is usually how strings are handled in Lisp dialects). So we can use JSON.parse and only replace \n with \\n (escape the new line).

if (atom.match(/^".*"$/)) {
   return JSON.parse(atom.replace(/\n/g, '\\n'));
}

So with this, we can have all escape characters for free (that is: \t or Unicode characters \u).

The next element of S-expressions are symbols. They are any character sequences that are not numbers or strings. We can create an LSymbol class, to distinguish from Symbol from JavaScript.

class LSymbol {
    constructor(name) {
        this.name = name;
    }
    toString() {
        return this.name;
    }
}

The function for parsing atoms can look like this:

function parseAtom(atom) {
    if (atom.match(int_re) || atom.match(float_re)) { // numbers
        return parseFloat(atom);
    } else if (atom.match(/^".*"$/)) {
       return JSON.parse(atom.replace(/\n/g, '\\n')); // strings
    } else {
       return new LSymbol(atom); // symbols
    }
}

Our parser function with add the parseAtom:

function parse(string) {
    const tokens = tokenize(string);
    const result = [];
    const stack = [];
    tokens.forEach(token => {
        if (token == '(') {
           stack.push([]);
        } else if (token == ')') {
           if (stack.length) {
               const top = stack.pop();
               if (stack.length) {
                  const last = stack[stack.length - 1];
                  last.push(top);
               } else {
                  result.push(top);
               }
           } else {
               throw new Error('Syntax Error - unmached closing paren');
           }
        } else {
           const top = stack[stack.length - 1];
           top.push(parseAtom(token)); // this line was added
        }
    });
    if (stack.length) {
        throw new Error('Syntax Error - expecting closing paren');
    }
    return result.map(Pair.fromArray);
}

We can also improve the toString method on Pair to use JSON.stringify for strings to distinguish from symbols:

class Pair {
    constructor(head, tail) {
        this.head = head;
        this.tail = tail;
    }
    toString() {
        const arr = ['('];
        if (this.head) {
            let value;
            if (typeof this.head === 'string') {
                value = JSON.stringify(this.head).replace(/\\n/g, '\n');
            } else {
                // any object including Pair and LSymbol
                value = this.head.toString(); 
            }
            arr.push(value);
            if (this.tail instanceof Pair) {
                // replace hack for the nested list because
                // the structure is a tree and here tail
                // is next element
                const tail = this.tail.toString().replace(/^\(|\)$/g, '');
                arr.push(' ');
                arr.push(tail);
            }
        }
        arr.push(')');
        return arr.join('');
    }
    static fromArray(array) {
        // ... same as before
    }   
}

And this is a whole parser. What's left are true and false values (and maybe null), but they are left as an exercise for the reader. The full code can be found on GitHub.

Different Approaches to Lisp parser in JavaScript

The above code is good for simple Lisp implementation. I used a similar code as the initial implementation of LIPS Scheme, which can still be found on CodePen.

Right now, LIPS uses a more advanced Lexer (using state machine) instead of a tokenizer. The Lexer was rewritten because the approach with stack was too difficult to modify.

NOTE: This article first appeared on the Polish blog Głównie JavaScript (ang. Mostly JavaScript), the article was titled: Parser S-Wyrażeń (języka LISP) w JavaScript.

This is how I usually work – I have a lot of tabs open and this speeds things up, because I don't need to wait for the next page to load.

But after I'd created the first PR in BitBucket and tried to go on to the next page, I was welcomed with an error message about an invalid CSRF token. This is a common problem with web applications that have CSRF protection.

So in this article you'll learn what CSRF is and how to fix this error.

Table of contents:

• What is CSRF?
• Standard CSRF protection
• The Problem with Tokens
• Cross-tab Communication Solution
  • Sysend library
  • Broadcast Channel
• Conclusion

What is CSRF?

CSRF is an acronym for Cross-Site Request Forgery. It is a vector of attack that attackers commonly use to get into your system.

The way you usually protect against CSRF is to send a unique token generated by each HTTP request. If the token that is on the server doesn't match with the one from the request, you show an error to the user.

Standard CSRF protection

This is one way you can protect against CSRF with a token:

const inital_token = '...';

const secure_fetch = (token => {
    const CSRF_HEADER = 'X-CSRF-TOKEN';
    return (url) => {
        const response = await fetch(url, {
            method: 'POST',
            headers: {
              [CSRF_HEADER]: token
            }
        });
        response.then(res => {
           token = res.headers[CSRF_HEADER]
        });
        return response;
    };
})(inital_token);

This code uses the fetch API to send and receive a secure token in HTTP headers. On the backed, you should generate the first initial token when the page loads. On the server, on each AJAX request, you should check to see if the token is valid.

The Problem with Tokens

This works fine unless you have more than one tab open. Each tab can send requests to the server, which will break this solution. And power users may not be able to use your application the way they want.

But there is a simple solution to this problem which is cross-tab communication.

Cross-tab Communication Solution

Sysend library

You can use the Sysend library, an open source solution that I've created specifically for this purpose. It simplifies cross-tabs communication.

If you want, you can use a native browser API like Broadcast Channel to do the same. More on how to do that later in this article.

But the Sysend library will work for browsers that don't support Broadcast Channel. It also works in IE (it has some bugs, which is not a surprise). You may also need to support some old mobile browsers. It also has a much simpler API.

This is the simplest example:

let token;
sysend.on('token', new_token => {
    token = new_token;
});

// ...

sysend.broadcast('token', token);

And this is how you would use this library to fix CSRF protection:

const inital_token = '...';

const secure_fetch = (token => {
    const CSRF_HEADER = 'X-CSRF-TOKEN';
    const EVENT_NAME = 'csrf';
    sysend.on(EVENT_NAME, new_token => {
        // get new toke from different tab
        token = new_token;
    });
    return (url) => {
        const response = await fetch(url, {
            method: 'POST',
            headers: {
              [CSRF_HEADER]: token
            }
        });
        response.then(res => {
           token = res.headers[CSRF_HEADER];
           // send new toke to other tabs
           sysend.broadcast(EVENT_NAME, token); 
        });
        return response;
    };
})(inital_token);

All you have to do is to send and receive a single message from other tabs when sending the request. And your CSRF protected app will work on many tabs.

And that's it. This will let advanced users use your app that has CSRF protection when they want to open many tabs.

Broadcast Channel

Here is the simplest possible example of using Broadcast Channel:

const channel = new BroadcastChannel('my-connection');
channel.addEventListener('message', (e) => {
    console.log(e.data); // 'some message'
});
channel.postMessage('some message');

So with this simple API you can do the same thing that we did before:

const inital_token = '...';

const secure_fetch = (token => {
    const CSRF_HEADER = 'X-CSRF-TOKEN';
    const channel = new BroadcastChannel('csrf-protection');
    channel.addEventListener('message', (e) => {
        // get new toke from different tab
        token = e.data;
    });
    return (url) => {
        const response = await fetch(url, {
            method: 'POST',
            headers: {
              [CSRF_HEADER]: token
            }
        });
        response.then(res => {
           token = res.headers[CSRF_HEADER];
           // send new token to other tabs
           channel.postMessage(token);
        });
        return response;
    };
})(inital_token);

As you can see from the above example, Broadcast Channel doesn't have any namespace for events. So if you want to send more than one type of event you need to create types of events.

Here is an example of using Broadcast Channel to do more than the CSRF protection fix we've discussed so far.

You can synchronize login and logout for your application. If you login into one tab, your other tabs will also sign you in. In the same way, you can synchronize the shopping cart in some e-commerce websites.

const channel = new BroadcastChannel('my-connection');
const CSRF = 'app/csrf';
const LOGIN = 'app/login';
const LOGOUT = 'app/logout';
let token;
channel.addEventListener('message', (e) => {
    switch (e.data.type) {
        case CSRF:
            token = e.data.payload;
            break;
        case LOGIN:
            const { user } = e.data.payload;
            autologin(user);
            break;
        case LOGOUT:
            logout();
            break;
    }
});

channel.postMessage({type: 'login', payload: { user } });

Conclusion

It's great if you protect your app against attackers. But keep in mind how people will be using your application, too so you don't make it unnecessarily hard to use. This applies not only to this particular problem.

The Sysend library is a simple way to communicate between open tabs in the same browser. And it can fix major issues with CSRF protection. The library has more features, and you can check its GitHub repo for more details.

Broadcast Channel is also not that complicated. If you don't need to support old browsers or some older mobile devices, you can use this API. But if you need to support older browsers, or want to make your code simpler, you use can the sysend library.

If you want to see browser support for Broadcast Channel, you can see Can I Use.