Deno - freeCodeCamp.org

Lume SSG Handbook – How to Create a Static Blog with Lume

Rajdeep Singh — Fri, 18 Nov 2022 17:06:55 +0000

Lume is a new static site generator based on Deno. Deno is a JavaScript-based run-time environment that supports TypeScript.

Lume is not built around any specific language. It supports Markdown, Nunjucks, TypeScript, and JavaScript by default. Lume also supports plugins. Some plugins come preinstalled by default. This is why Lume itself is template-language agnostic.

Before learning more about Lume, let's discuss Deno and consider some important Deno features.

What is Deno?

Deno is an alternative to Node.js built by Ryan Dahl (who also developed Node). Deno is based on the Rust programming language, and the second main component in Deno is the JavaScript V8 engine for WebAssembly.

Deno has many cool features – it's fast, secure by default, is compatible with web assembly and has TypeScript support, has in-built development tools, and more. Deno also supports Node.js APIs so you can use all npm packaged with Deno.

In Deno, you do not need to create a configuration file to run a simple program. You simply deploy your website instantly with a second on-edge network. But my final favorite feature is the new node_modules folder in the workspace. Deno caches all the packages locally and uses them, which is very fast compared to Node.

You can check out the demo blog website here, and all the code is available on GitHub here.

Now let's dive into the tutorial.

Lume + Markdown
Why is Lume special?
How does Lume compare to other static site generators?
How to start a new project with Lume
Lume folder structure
Additional folders
How to create global data
How to create a dynamic page
How to create a Home and Pagination page
How to build an articles page
How to generate a category page
How to generate a tag page
How to enable search functionality
How to install page find
Lume SEO
Lume Sitemap
Lume plugins
How to enable comments
How to use Netlify CMS with Lume
How to deploly your blog with Deno Deploy
Github pages
Conclusion

Lume + Markdown

Lume is a new static site generator based on Deno created and maintained by Óscar Otero. Lume uses markdown-it as the default markdown. You can use the remark plugin to change the default markdown.

Markdown is a language that helps to write documents, readme files, and blogs on the internet. John Gruber created markdown in 2004.

Markdown-it is similar to GitHub-flavored Markdown (GFM) markdown. GFM and markdown-it both follow the exact markdown specifications.

If you've worked with GitHub and written README files, that means you are likely familiar with GFM markdown. If you don't like the default (markdown-it) markdown, you can change the markdown with the remark plugin.

There are tons of static site generators. So why is Lume special? What does it provide compared to other static site generators? Let's find out.

Why is Lume special?

As you know, Lume is built on Deno, and Deno is a Node.js alternative—that is why Lume provides lots of features out of the box.

Lume works similarly to a GitHub readme file. If you're familiar with writing one of those (and using markdown), you do not need to learn anything else to write articles and documentation with Lume.

Here are some benefits of Lume:

Lume supports multiple template engines like Markdown, Nunjucks, Eta, JSX, Liquid, or Pug.
It supports multiple authors
It has code syntax highlighting
There's great SEO support
Lume supports multiple languages
It has Windi CSS support
There's pagination and component support
It supports minifying JavaScript, HTML, CSS, and SASS
It has relations support
There is the built-in search functionality
It supports Netlify CMS
It supports images and SVGs
There's Remark.js plugin support
You can deploy with Netlify, Vercel, GitLab Pages, and the GitHub page.

How Does Lume Compare to Other Static Site Generators?

Lume is a new static site generator compared to others, but it comes with many configuration options, and you can do anything with it. You don't even need to use any third-party plugins.

With Lume processors and preprocessors, you can easily manipulate the HTML code with the JavaScript DOM API. Other static site generators support a few template engines, but Lume supports many template engines like JavaScript, JSX, Nunjucks, Eta, JSX, Liquid, and Pug.

Note that Lume can seem tough to get started with for beginners. But if you're following my article, just make sure to open the code which will make things much clearer for you.

How to Start a New Project with Lume

You can set up a new project with the Lume CLI with this command:

deno run -Ar https://deno.land/x/lume/init.ts

Lume installation demo

Follow these steps:

First, create an empty mkdir lume-deno folder project.
Then run the lume init.ts command.
Select an available plugin from the list.

And you should be up and running.

Lume Folder Structure

After the installation finished, we saw three files:

_config file is used to configure Lume.
deno.json is a defined script or task for Deno.
import_map.json is to help you import a Deno package for the internet.

lume default folder structure

How to run the Lume server

To run a local development server, you'll use the deno task lume --serve command. To build a website, run the deno task build command.

If you face a 404 - not found error, you can create a index.njk file within the root folder.

In the index.njk file, paste the following code.

---
title: "hello"
---
hello world

And you'll see the following output:

Lume hello-world

Additional folders:

posts folder is not a compulsory folder. It contains all your posts' markdown files.
pages folder is not a compulsory folder. It has all your pages' markdown files.
author folder is not a compulsory folder. It has all your author markdown files.
_components folder is a compulsory folder. It has all your components.
_includes folder is a compulsory folder. It contains your layout and templates for your site.
images folder is not a compulsory folder. It contains all your images.

The posts, pages, authors, and images folders are optional. You can rename these folders according to your wishes. The _components and _includes folders are mandatory and you don't rename them.

The difference between components, layout, and template are as follows:

The components are reusable code
The layout and template are not reusable like components.

How to Create Global Data

In Lume, you can create a data variable, which has access to the entire website by all template engines.

// Set a variable
site.data("post_per_page", 10);

// Set a function
site.data("randomNumber", function () {
  return Math.random();
});

How to create posts, pages, and author markdown files

You create posts, pages, and author folders in the root folder. Then, inside every folder, you write markdown files.

You can access all posts, pages, and authors by file name on the browser:

localhost:3000/posts/your-title.html
localhost:3000/pages/your-pages.html
localhost:3000/author/your-author.html

Suppose you need a demo post, pages, and author markdown for a project or template. Then, you can use demo-markdown posts for your project. It is free and open source, and you can create your own template.

How to create a dynamic page

In Lume, .tmpl.js and .tmpl.ts extensions use JS and TS as template engines. You can use them with regular pages or dynamic pages to create categories, tags, pagination, and so on for your website.

How to create a home and pagination page

The home page is based on pagination, and pagination is based on posts. Lume dynamically generates the pagination.

In Lume, I chose nunjucks and JavaScript to create my demo website. Nunjucks is the default template engine. You can easily change the default Nunjucks engine with another template engine with copy-paste code.

home page

Lume provides a JavaScript template function that helps create dynamic web pages. If you create a home page for the site, you need to create an index.tmpl.js file in your root or src folder. Lume also supports an src folder to organize your project. In my demo project, I'm not using the src folder.

The *.tmpl.js is an extension of a JavaScript template that helps create dynamic pages for websites. It comes pre-installed in Lume with the modules plugin.

For example, the following code creates pagination for your website. But the layout comes from the _includes folder.

// index.tmpl.js

// title for SEO
export const title = "Minimalist blog"
// description for SEO
export const description = "Minimalist blog theme is liteweight and work with lume."

export default function* ({ search, paginate }) {

//  Get all posts of type article.
  const posts = search.pages("type=article", "date=desc");

  // Configation for pagination
  const options = {
    // Page 1 is the homepage, set "/" as url
    url: (n) => n === 1 ? "/" : `/page/${n}/`,
    // par page posts
    size: 7,
  };

  // Yield the pages, but the index needs a different layout
  for (const page of paginate(posts, options)) {

    //  if home page, use diffrent layout "/"
    if (page.pagination.page === 1) {
      page.menu = {visible: true, order: 1, title:"Home" }
      page.title = "Home page"

      //  comes from _includes folder

      page.layout = "layouts/home.njk";
    } else {
      // Render diffrent layout if it is not home page page "/page/2","/page/3",etc
      page.title = "Pagination page"

      page.layout = "layouts/home.njk";
    }

    yield page;
  }

}

‌Lume has a search plugin that helps you search pages. In my demo blog, I search all pages base on the type.

In my all posts folder, all posts are defined in type=article, the author is described in type=author, and pages are defined in type=page . The search plugin is pre-installed with Lume.

On index.tmpl.js file, you can get all pages that have the type "article" (type=article ) using the following code: const posts = search.pages("type=article", "date=desc");. The search.pages("type=article", "date=desc") function only returns those that have type=article .

The layouts/base.njk layout file contains an HTML base and includes a header and footer for the website.



  
    
    
    {{ title }}
    
   
  

    {% include "layouts/header.njk" %}

    
      {{ content | safe }}
    

    {% include "layouts/footer.njk" %}

Inside the {{ content | safe }}, Lume renders other HTML, like cards, articles, home templates, Tag and category pages, and so on.

// rest code ...
  for (const page of paginate(posts, options)) {
  }
// rest code ...

I used the for loop on the index.tmp.js file that helps get all the posts and send them to the layouts/home.njk file and the layouts/home.njk file. You get all posts from the result, and then pass them to the card.njk template.

---
layout: layouts/base.njk
---

{% for post in results %}
    {% include "templates/card.njk" %}
{% else %}
     Posts is empty 
{% endfor %}

{% include "templates/pagnation.njk" %}

‌The templates/card.njk file runs for all blogs and generates HTML for each blog. Your card looks like this:

card.njk

In card.js template, you can access it using {{}} curly brackets. Get the title using {{post.data.title}} and {{post.data.description}}.

In my demo blog, I'm getting only the first category to show inside the card. So I use a defined filter _config.ts and use it with | symbols. Inside card.njk we get a zero index or first value in from categories with the following code: {{ post.data.category | category }}.

To get the author on card.njk I define the relationship between the article and the author type, which you can learn about from the docs.



    

        

        

            
                {{ post.data.category | category }}
            

            {{ post.data.title }}

            
                {{ post.data.description }}
            

            Read more


            

                {% if post.data.author.length <= 2 %}

                    {% for author in post.data.author %}

                        

                        
                            
                                {{ author.author_name}}
                            
                                {{author.job}}
                            
                        
                    {% endfor %}
                {% else %}

                    

                    
                        
                            {{ post.data.author.author_name}}
                        
                            {{post.data.author.job}}
                        
                    
                {% endif %}

The {{ title }} and {{description}} both show the markdown file title and description. To show the category, I used a filter to show a single category on the article page and define the filter on _config.ts file. I also show single and multiple authors with For loop. Every card has its own post.data.url property, after the user clicks on the read more button user ago respected the article read page. To show the image, I used {{ post.data.image }} property. I also show single and multiple authors with For loop on card.njk file.

How to Build an Articles Page

I know the page containing the article content is one of the most important for a blog. It's where readers should spend most of their time rather than the website's home page.

---
category:
  - Blog
date: 2022-03-20T13:09:24Z
description: Dolor excepteur ad ad fugiat Lorem consectetur velit excepteur duis qui.
image: /images/dice.jpg
tags:
  - npm
  - npm cli
  - npm install command
title: Random blog Title for markdown.
draft: false
author_id: 1
type: article
layout: templates/article.njk
---

Laboris consequat elit ad excepteur. Ipsum duis amet dolore voluptate dolore consequat ullamco incididunt ullamco. Dolore laborum cupidatat dolor ipsum reprehenderit excepteur cupidatat dolore.

## First
Cupidatat non amet irure esse quis aute qui enim. Est qui ullamco proident consequat aute reprehenderit eiusmod nisi. Laboris ullamco fugiat sint occaecat.

## Second 
Irure fugiat officia non esse esse irure eu sint commodo quis amet. Dolor culpa non amet elit adipisicing exercitation ex anim velit ipsum.

## conclusion
Culpa irure eiusmod labore ut proident sit enim laborum nulla voluptate eu. Id tempor velit cillum pariatur est laboris ipsum ad. Sint nostrud nostrud laboris Lorem consequat tempor voluptate dolore velit. Commodo elit nulla commodo pariatur. Deserunt ipsum fugiat id ipsum pariatur cupidatat magna ex. Fugiat aliquip nisi laboris aliquip velit velit id quis eu reprehenderit excepteur fugiat.

I created an article in the posts folder under type=article . The author_id defines the relation between the author and the article.

I used templates/article.njk as the layout for my articles page. You can design yours as per your requirements. You can design the article title, description, author card, and tags as well.

---
layout: layouts/base.njk
---

  

    {{ title }}
    {{ description }}

    {% if author %}
      


        {% if author.length <= 2 %}

          {% for author in author %}

            

            
              
                {{ author.author_name}}
              
                {{author.job}}
              
            
          {% endfor %}

        {% else %}

          

          
            
              {{ author.author_name}}
            
              {{ author.job}}
            
          
        {% endif %}

      

    {% endif %}

      
        {% for tag in tags %}
          {{ tag }}
        {% endfor %}
      

    
      {{ date | date('HUMAN_DATE') }}
    


  

  
    {{ content | safe }}
  


{%- set previousPost = search.previousPage(url, "type=article") %}

{% if previousPost %}
  
    {%- if previousPost %}
      
      ← Previous: {{ previousPost.data.title }}
      
    {% endif %}

    {%- set nextPost = search.nextPage(url, "type=article") %}
    {%- if nextPost %}
      
        Next: {{ nextPost.data.title }} →
      
    {% endif %}
  
{% endif %}

 

{# ==== #}
{#  Addding the utteranc Commenting script #}
{# ==== #}

 Comment

The layouts/base.njk file is the base file for our blog (which I've already explained). The {{ title }} and {{description}} both show the markdown file title and description.

To show tags on the article page, I used a for loop. I also showed single and multiple authors with the for loop.

To convert the date into a human-readable format, I used Lume date plugin and wrapped it with a date filter that looks like this: {{ date | date('HUMAN_DATE') }}. To show all markdown paragraphs, I used {{ content | safe }} .

For pagination, I used the Lume pagination plugin, and with the search.previousPage(url, "type=article") function, I showed the next and previous posts on the article page. For comments, I used utteranc.es.

How to Generate a Category Page

In Lume, you create a dynamic category based on article type. Lume also provides inbuilt functionality called a JavaScript template engine that helps you create a dynamic page. It is similar to creating pagination functionality.

In Lume, there's a special file called .tmpl.js that helps you create a dynamic category.

export const layout = "layouts/category.njk";

export default function* (props) {


  const { search }= props

  for (const category of search.values("category") ) {

    yield {
      url: `/category/${category}/`,
      title: `Categoryed ${category}`,
      type:"category",
      category,
    };

  }

}

In lume search.values() have a function that helps you find a category using markdown meta tags and sends data into the layout/category.njk file. It will generate all categories with the following URLs like /category/android/ , /category/android-phone/ , /category/human/ and so on.

How to Generate a Tag Page

Generating a dynamic tags page is similar to a category. Lume provides a special search.tags() function to generate tags:

export const layout = "layouts/tag.njk";

export default function* ({ search }) {

  for (const tag of search.tags()) {
    yield {
      url: `/tag/${tag}/`,
      title: `Tagged ${tag}`,
      type: "tag",
      tag,
    };
  }
}

The following code generates all tags with the following URLs like /tag/android/, /tag/android-phone/, /tag/human/ and so on.

How to Enable Search Functionality

Lume has many in-built plugins which provide an excellent development experience. You can solve lots of problems with Lume plugins, and they allow you to add and remove features easily.

Lume provides inbuilt search functionality for the site. You enable it with the lume page find plugin.

Add a search bar in lume

How to Install Page Find

The Lume page finds plugin provides you with a search bar. Simply copy the following code and paste it into the _config.ts file and restart your server.

import pagefind from "lume/plugins/pagefind.ts";

How to configure the page find plugin

You configure the plugin in the _config.ts fil. You can also change the default config.

// rest of code ...
import lume from "lume/mod.ts";
import pagefind from "lume/plugins/pagefind.ts";

const site = lume();

// config the pagefind plugin with default config
site.use(pagefind());

 // or 

// change the default config in pagefind plugin
site.use(pagefind({
  ui: {
    containerId: "search",
    showImages: false,
    showEmptyFilters: true,
    resetStyles: true,
  },
}));

export default site;

Lume SEO

Lume has a plugin to help with SEO called metas. With the plugin, you can easily add various SEO-friendly configurations.

How to install metas

You install all plugins within the config.ts file. Copy the following code and paste it into the config.ts file, then restart the server.

import metas from "lume/plugins/metas.ts";

How to configure metas

You can configure metas in various ways in the _config.ts file. See the comments below:

import lume from "lume/mod.ts";

// install metas plugin for SEO
import metas from "lume/plugins/metas.ts";

const site = lume();

// config the metas plugin with default config
site.use(metas());

or

// add custom config 
site.use(metas({
  defaultPageData: {
    title: "title", // Use the `title` value as fallback.
  },
}));


export default site;

How to Use the Metas SEO Plugin in Lume

To use the SEO metas plugin, you'll need to create a _data.yml file in the root of the project folder and paste the following code into it:

metas:
  site: Minimalist blog
  twitter: "@Official_R_deep"
  icon: /images/icon.png
  lang: en
  generator: true

mergedKeys:
  metas: object

The following code helps you create all the various SEO tags for your website, and you can easily extend it with the metas plugin in Lume.

Lume Sitemap

Lume has a plugin called sitemap. This plugin helps you create sitemaps for your blog. With Lume 13 you do not need to create a sitemap manually.

How to install the sitemap plugin

You install all plugins within the config.ts file. Copy the following code and paste it into the config.ts file, then restart the server.

import sitemap from "lume/plugins/sitemap.ts";

How to configure the sitemap plugin

You can configure the sitemap plugin in various ways in the _config.ts file. See the comments below:

import lume from "lume/mod.ts";
import sitemap from "lume/plugins/sitemap.ts";

const site = lume();

site.use(sitemap());

// or

// add custom config 
site.use(sitemap({
  filename: "my-sitemap.xml", // to change the sitemap filename
  query: "indexable=true", // Select only pages with the indexable attribute as true
  sort: "date=desc", // To sort by data in ascendent order
}));

export default site;

How to use the sitemap plugin in Lume

You do not need any special file to use the site map plugin. Simply add the plugin after calling the plugin in config.ts and it'll start working on your site. This creates the sitemap.xml file and you can change the file name with a custom configuration in _config.ts file.

How to access the sitemap on the website

You can access the sitemap with the filename, for example by default in the localhost [http://localhost:3000/sitemap.xml](http://localhost:3000/sitemap.xml) and production [http://my-domain-name/sitemap.xml](http://localhost:3000/sitemap.xml) .

Lume Plugins

Lume comes with inbuilt plugins, but you can easily add or remove features according to your requirements. You do not need all the stuff on your site – you can configure everything as you wish.

You can add more template engines, minify HTML, CSS, and JavaScript with plugins, enable code highlighting, date manipulation, image manipulation, SVG support, and more.

You can also easily create your own plugins with lume. Lume also provides excellent documentation where you can learn more.

How to Enable Comments

To add comments on your Lume site, I think utteranc.es is the best choice for all static site generators. utteranc.es is an open-source commenting system based on GitHub. It looks like this:

Enable comment

If you want to enable comments on the site, the first step is to install an utterances application on GitHub. Then, copy and paste the following code into the article read file or where you show comments on the site.

Next, you'll need to change the utterance comment script. The first change in the repo repo="your-github-repo" name is compulsory. The others are not. You can adjust according to your requirements – for example, changing the theme, issue term, and so on.

To read more about utterance, here's a great article written by Josh Collinsworth.

The best approach is to add utterance comments in lume and then read the GitHub discussion.

How to Use Netlify CMS with Lume

Netlify CMS is an open-source content management system. You can easily integrate Netlify with Lume using the netllify_cms plugin. It is provided by Lume, and you just need to install it and copy/paste the code.

How to Install the Netlify Plugin

Import the Netlify plugin in your _config.ts file to use it like this:

import lume from "lume/mod.ts";
import netlifyCMS from "lume/plugins/netlify_cms.ts";

const site = lume();

site.use(netlifyCMS());

export default site;

To configure it, you'll need to create a /_data/netlify_cms.yml file in the root level and then paste the following code after restarting your server:

backend:
  name: git-gateway
  branch: master

media_folder: statics

collections:
  - label: Posts
    name: posts
    description: List of posts
    folder: posts
    extension: md
    create: true
    fields:
      - label: Title
        name: title
        widget: string
      - label: Content
        name: body
        widget: markdown

Netlify will ask you for permissions for the CMS proxy. Type npx netlify-cms-proxy-server in a terminal, press enter or type y, and your Netlify CMS will start running locally on http://localhost:3000/admin URL. Now your Lume blog is ready for deployment on Netlify.

How to Deploy Your Blog with Deno Deploy

You can deploy Lume on various platforms such as Deno Deploy, GitHub Pages, Gitlab Pages, Netlify, Vercel, Fleek, AWS Amplify, and Cloudflare Pages. Lume also provides excellent documentation on deployment.

In this article, I'm deploying my Lume blog with Deno Deploy (and we'll also see how to do it with GitHub pages). Deno Deploy is an official platform built by the Deno team to deploy Deno-based applications.

Before deploying your Lume blog on Deno Deploy, make sure you create a server.ts file in the root level.


import Server from "lume/core/server.ts";

const server = new Server({
  port: 8000,
  root: `${Deno.cwd()}/_site`,
});

server.start();

console.log("Listening on http://localhost:8000");

Deployment Steps:

Create an account on Deno Deploy.
Push your local code to GitHub and then select the server.ts file. Deno Deploy automatically creates a site based on the server.ts the file.
Make sure to first create a custom server.ts file. Then move to the next step.
The easiest way to deploy your site is with GitHub Actions. Create a new .github/workflows/deno.yml file in your project root level and paste the following code into it:

name: Deploy
on: [push]

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    permissions:
      id-token: write # Needed for auth with Deno Deploy
      contents: read # Needed to clone the repository

    steps:
      - name: Clone repository
        uses: actions/checkout@v3

      # TODO: add a build step here

      - name: Upload to Deno Deploy
        uses: denoland/deployctl@v1
        with:
          project: "minimalist-blog"
          entrypoint: "./serve.ts"

How to Deploy Your Blog with Github Pages

GitHub Pages are free static sites you can use to host pages. You can also deploy your Lume blog it. The process of deployment is pretty easy.

To deploy Lume on GitHub pages you need to have GitHub Actions set up.

Deployment Steps

It's best if you have a GitHub repository so you can convert your local website to GitHub Pages.
Create a new repo and push all your local code into it.
Create a new .github/workflows/deno.yml in your project root level, then paste the following code into it and push it into the GitHub repo. The GitHub action runs based on the github.yml action and it generates a GitHub page.

name: Publish on GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Clone repository
        uses: actions/checkout@v3

      - name: Setup Deno environment
        uses: denoland/setup-deno@v1
        with:
          deno-version: v1.x

      - name: Build site
        run: deno task build

      - name: Deploy
        uses: crazy-max/ghaction-github-pages@v3
        with:
          build_dir: _site
        env:
          GITHUB_TOKEN: ${{ secrets.MY_GITHUB_TOKEN_PAGE }}

You need a GitHub token to deploy your Lume website to GitHub pages. This is a required part of the setup. I found a great article written by Davide that can help you learn more about GitHub Actions and how to create one.

GitHub Actions takes two or three minutes to finish hosting your website on GitHub Pages.

Check out the GitHub repository to learn how to configure the GitHub workflow for GitHub pages. You can also see a live demo website on the GitHub page.

A quick note: if you deploy your Lume site on GitHub pages and your image does not show on the website, there are two possible reasons for this:

If all image names aren't in lowercase, you might get an error. To resolve the error, convert your image names into lowercase with this command: your.github.com/your-reponame/images/my-image.png
If you're using the base_path and relative_urls Lume plugins in your project and relative_urls is redundant, and then you'll need to remove the relative_urls plugin in your project. Your image should now work fine.

Conclusion

Lume is an easy-to-learn and feature-rich static site generator. You can do anything you imagine with it. Lume gives you a lot of freedom with the code.

The Lume community is not as big as those of Hugo, 11ty, Jekyll, and other tools. But, the Lume maintainers actively reply to everybody who comments in the GitHub discussion. Without a strong community, this tool should be able to create a strong impact.

One challenge with Lume is that it's tough to get started for beginners and is more suited to intermediate and advanced developers. If you're jumping right into using Lume as a beginner, you might struggle with a lack of background knowledge about how static site generators work.

Because of this, it's helpful to have a little bit of knowledge about Nuckjunks, JSX, and other template engines that work based on markdown. Once you gain this experience, then you'll easily be able to use Lume to design your markdown-based blog.

I recommend using the lume MDX plugin for markdown. You can use JSX-based components inside the markdown file, and you can create beautiful code blocks, tip blocks, and so on.

I highly encourage all developers to try Lume out. If you have problems with Lume, you can reach out to its creator on the GitHub discussion and the Discord server.

If your course is about Computer science, Bioinformatics, and Biotechnology. You can join my free newsletter.

How to Use SurrealDb with the Fresh Framework and Deno

Rajdeep Singh — Fri, 23 Sep 2022 17:51:53 +0000

SurrealDB is a newly launched database that has recently started gaining popularity in the programming world.

SurrealDB was built with the Rust language and was created by Tobie Morgan Hitchcock and Jaime Morgan Hitchcock.

SurrealDB's new database comes with many features, but I'm most interested in the Deno surrealDB library.

In this article, we'll create a simple todo app with the Fresh framework and SurrealDB database. We'll use the Fresh framework to build out the API with surrealDB.

The Fresh framework is a new JavaScript framework introduced by Deno itself. Fresh uses the Preact library to design and build components. Fresh comes with inbuilt TypeScript and Tailwind CSS support and Island-based architecture. There's also no configuration needed.

Deno and Fresh are production ready. So you can build any web app and deploy it with one single click. But keep in mind that SurrealDB may not be. According to their docs, SurrealDB is production ready but the documentation is not super clear on the issue.

All the code is available on GitHub.

Here's a Demo of What We'll be Building:

TODO Application demo

How to Install SurrealDB, Deno, and the Fresh Framework

There are three requirements to follow along with this tutorial: the first is having Deno installed, the second is having the SurrealDB database, and the last one is using the Fresh framework.

First, we'll install the surrealDB database and the Fresh framework with Deno. You can skip this part if you have already installed both Deno and the SurrealDB packages.

How to Install the SurrealDB database on Linux

The SurreadDB installation process is pretty easy for all operating systems. For example, in Linux, you can install the database with one single curl command.

If you have a different operating system, I suggest reading the SurrealDB installation docs.

In Linux, use this command:

curl -sSf https://install.surrealdb.com | sh

Install the SurrealDB database in Linux.

To start the surrealDB database in Linux, run the following command:

surreal start --log debug --user root --pass root memory

You use the --user flag for your username. In my case, my username is root.
You use the --pass flag for your password. In my case, my password is root.

To learn more about all the flags or options, run surreal start --help command. This is what you'll see:

Now you're ready to use the SurrealDB database.

How to Install Deno on Linux

Deno is a newer JavaScript run time environment. It's fast and secure when you compare it to Node.js.

To learn more about Deno, you can read this helpful tutorial I found on freeCodeCamp written by Brian Barrow.

To install Deno on Linux, you need one command:

curl -fsSL https://deno.land/install.sh | sh

Install deno in Linux

How to Install the Fresh Framework with Deno

Fresh is a new JavaScript framework based on Deno. The Fresh framework supports TypeScript by default. In addition, Fresh sends zero DB of JavaScript by default to the client.

You can set up a Fresh project with the following command:

deno run -A -r https://fresh.deno.dev my-new-fresh-project

You can run a local development server with deno task start .

Note that both the Fresh framework and SurrealDB use the same 8000 port. In the SurrealDB, I didn't find any document about port changing. But in Fresh, you can easily change the port inside main.ts file. Then, without changing the port, your Fresh localhost redirects the SurrealDB local host.

For example, you can change the port in Fresh like this:

// change port in main.ts

await start(manifest, { port:3002, plugins: [twindPlugin(twindConfig)] });

Fresh Framework Project Structure

The project folder structure is pretty straightforward. For this project, we must follow the folder and file structure to create a todo list app with SurrealDB.

File and folder structure

Let's further discuss some essential files here:

The components folder helps contain all custom components built with Preact.
In the deno.json file you add tasks and the importMap file. Tasks are similar to scripts in Node, and in the importMap section, you pass a JSON file that contains all your import packages from Deno.
dev.ts is a file created only for development.
fresh.gen.ts generates and updates automatically based on dev.ts. It includes all routes, islands, and other configurations.
The import_map.json file contains imports of all packages which you need to run your project.
Islands enable client-side browser-based interactivity in Fresh. Basically, with the island folder, you send JavaScript to the browser. By default, the Fresh framework sends zero KB JavaScript.
main.ts is the main entry point that helps start your application.
The routes folder handles your path and API. It is similar to the Next.js pages folder.
The static folder contains all static files like JavaScript, images, and fonts under a root directory. All are accessed by reference and start with the base URL (/). For example, /logo.svg.
twind.config.ts configures Tailwind CSS
The utility folder contains the database configuration.

You can learn more about folder structure from Fresh's official docs.

Again, to run a local development server, use the command deno task start .

How to Install the SurrealDB Database Library in the Fresh Framework

You need the Deno-based surrealDB library (module). It's a SurrealDB library created by the SurrealDB team.

The SurrealDB library (module) helps you connect your application to your database. The surrealDB module connects your local and remote databases very easily.

To install the SurrealDB module in the Fresh framework, simply copy the following code and paste it into import_map.json file:

  "surrealdb" : "https://deno.land/x/surrealdb@v0.2.0/mod.ts"

_Paste the following code into import_map.json file_

How to Setup the SurrealDB Database in Fresh

The first step is to create a setup file for the SurrealDB database. The setup file helps you connect the Fresh framework to the SurrealDB database.

In my case, I create a database setup in a separate utility/database.ts file. The separate file helps reduce your code and is easier to manage.

// utility/database.ts

//  import surrealdb 
import Surreal from "surrealdb";

// load Environment Variables
import "https://deno.land/x/dotenv@v3.2.0/load.ts";

// get DATABASE_URL url
const domain = Deno.env.get("DATABASE_URL")

// surreal database
const db = new Surreal(domain);

// signin
await db.signin({
    user: 'root',
    pass: 'root',
});



//  Select a specific namespace /  database
await db.use('test', 'test');

export default db

To connect the database, ensure that your database is running and your password and username match your database conditionals.

For example, run your local SurrealDB user name and password that's the same as in your utility/database.ts file.

surreal start --log debug --user root --pass root memory

How to Use SurrealDB Module (Library) Methods

The SurrealDB module comes with inbuilt methods. All the methods help you perform CURD operations on the SurrealDB database. These methods allow you to create quickly and get, update, and delete things from the database.

In this article, we'll use four methods which are create() , update() , delete() and select().

There are other methods provided by SurrealDB, which you can read about on the surrealDB module documentation page.

How to Create the API Endpoints

To create a Todo app, you need four endpoints. We'll use the Fresh framework to create APIs. All the API routes go in the routes/api folder.

Get
Post
Isdone (Update)
Delete

The Get API

The Get API lets you show all data from the todo table. To access all data from Todo table, you need a select() function provided by the SurrealDB module.

import { HandlerContext } from "$fresh/server.ts";
import db from "../../utility/database.ts";


export async function handler(_req: Request, _ctx: HandlerContext) {

    try {
        // get all todo list
        const todo = await db.select("todo");

        // return todo 
        return Response.json(JSON.stringify(todo))

    } catch (error) {

        return new Response(error);
    }


}

The Post API

In the Post API, you'll create a new todo based on the title. All the todos are saved inside the todo table. With the get API, you access all todos from the todo table.

To create a new todo item in the database, you can use the SurrealDB module's inbuilt create() function.

import { HandlerContext } from "$fresh/server.ts";

// import module uuid from deno 
import * as mod from "https://deno.land/std@0.156.0/uuid/mod.ts";

// import database 
import db from "../../utility/database.ts";


export async function handler(_req: Request, _ctx: HandlerContext) {
    // get url
    const url = new URL(_req.url);

    // get title from url
    const title = url.searchParams.get("title") || "";

    try {

        // Create a new person with a random id

        const NAMESPACE_URL = "6ba7b810-9dad-11d1-80b4-00c04fd430c8";

        // create a unique uuid for demo purposes
        const uuid = await mod.v5.generate(NAMESPACE_URL, new TextEncoder().encode("python.org"));

        // create new data based on value
        const created = await db.create("todo", {
            uuid: uuid,
            title: title,
            isDone: false
        });

        // return data
        return Response.json({ sucessfull: "your data submit sucessfully", created })

    } catch (error) {

        return new Response(error);
    }


}

The Isdone (Update) API

The Isdone API helps to update the todo items inside the todo table. To update data from the table the surrealDB module provides an inbuilt update function for this.

With the update function, you can promptly update the todos by one or more items in one request.

import { HandlerContext } from "$fresh/server.ts";

// import database 
import db from "../../utility/database.ts";



export async function handler(_req: Request, _ctx: HandlerContext) {
// get URL
  const url = new URL(_req.url);
  // get todo id based on id we update todo.
  const todoid = url.searchParams.get("todoID") || "";
  // get title
  const todoTitle = url.searchParams.get("todoTitle") || "";
  // get uuid
  const todoUuid = url.searchParams.get("todoUuid") || "";


    try {

        // update the todo
        const person = await db.update(todoid, {
            isDone: true,
            title: todoTitle,
            uuid: todoUuid
        });

        return Response.json({sucessfull:"your data submit sucessfully ",person})

    } catch (error) {

        return new Response(error);
    }


}

The Delete API

You use the Delete API to delete a todo from the todo list. You'll use the inbuilt delete() function. With this inbuilt function, you can quickly delete a todo based on the todo's id.

import { HandlerContext } from "$fresh/server.ts";

// import database 
import db from "../../utility/database.ts";



export async function handler(_req: Request, _ctx: HandlerContext) {
    // get url
    const url = new URL(_req.url);

    // get todo id – based on id we delete todo.
    const todoid = url.searchParams.get("todoID") || "";


    try {

        // delete specified todo item 
        await db.delete(todoid);

        return Response.json({ sucessfull: "your data submit sucessfully " })

    } catch (error) {

        return new Response(error);
    }

}

How to Create the UI for the Todo App

UI for dashboard

The Box.tsx and Item.tsx files come from an island folder. Both files are known as components. In both components, we need JavaScript integration. For that reason, we create both components inside the island folder.

Index page

The index page shows that both the Box.tsx and Item.tsx files come from the island. We'll design the home (Index) page layout with them.

import { Handlers } from "$fresh/server.ts";

//  Import Box components from island
import Box from "../islands/Box.tsx";

//  Import Item components from island
import Item from "../islands/Item.tsx";

// to load Environment variable 
import "https://deno.land/x/dotenv@v3.2.0/load.ts";

// get Environment variable 
let domain= Deno.env.get("DOMAIN")


interface todo {
  id: string;
  title:string;
  isDone:boolean
}

//  Call get API with fresh handler
export const handler: Handlersnull> = {

  async GET(_, ctx) {

    // call get api
    const response = await fetch(domain + "/api/get").then(      
      (response)=> response.json()
    ).then(
      (response)=> JSON.parse(response)
    ).catch(
      error=> console.log(error)
    );

    //  pass data into component props
    return ctx.render(response);
  }
};

export default function Home({data}: { data: any; }) {
  return (
    class="h-screen w-screen flex flex-col items-center justify-center bg-blue-600 font-sans">
      class="flex flex-row w-4/6 justify-center mx-auto">
        class="m-2 p-1 text-5xl font-mono font-serif cursor-pointer">Deno
        class="m-2 p-1 text-5xl font-mono font-serif cursor-pointer">SurrealDB
      

      class="bg-white rounded shadow container mx-auto p-3 m-4 w-3/6 lg:w-3/6 xl:w-3/6 md:w-3/6 2xl:w-3/6 ">
            class=" flex mb-4 flex-col py-2">
                class="text-gray-500  text-lg">Todo List
                
            
            class="p-2">
              {
                data.map( (item: any) => 
                  
                )
              }
            
        
    
  );
}

The Box.tsx Component

The Box component helps call the post API and create a new todo in the database. Box.tsx is an island-based component that's created with Preact. Preact is similar to React, but Preact is a lightweight version of the library.

On the Box component, we get the value in the input with the onChange Event. Then, after the user clicks on the add button, we call the post API to create a new todo in the SurrealDB database.

Design the box component with fresh framework

import { useState } from "preact/hooks";

// import Notification from components
import Notification from "../components/Notification.tsx";

interface todo {
    id: string;
    title: string;
    isDone: boolean
}


export default function Box({ data }: { data: any; }) {

    //  title
    const [title, setTitle] = useState("");

    // show Notification based on success
    const [successful, setSuccessful] = useState(false);


    function submit() {

        if (title) {
            //  call post api 
            fetch(`/api/post?title=${encodeURIComponent(title)}`)
                .then((res) => res.json())
                .then((data) => {
                    console.log("your data submit sucessfully ");

                    // change false to true
                    setSuccessful(true)
                });
        }
    }



    return (
        <>
          <Notification  successful={successful}  setSuccessful={setSuccessful} />

            <div class="flex mt-4 justify-between">
                <input onChange={(event) => setTitle(event.currentTarget.value)} class="shadow appearance-none border rounded w-full py-2 px-3 mr-4 text-gray-600" placeholder="Add Todo" />
                <button onClick={submit} class="flex-shrink p-2 border-2 rounded text-purple-500 border-purple-500 hover:text-white hover:bg-purple-500 w-24">Addbutton>
            div>
        
    );
}

The Item.tsx Component

Item component calls two APIs – one is the delete API and the second is the update API. The delete API deletes an item from the todo table and the update API updates item in the todo table in the database.

Item.tsx is an island component similar to the Box component. The item component is also built with Preact.

Our first button changes based on whether the todo is complete or pending, and the second button deletes the todo based on the Todo's ID.

First, we get the value in the input with the onChange Event. And after the user clicks on the add button, we call the post API to create a new todo in the SurrealDB database.

When the remove button gets clicked, we call the delete API with the todo ID to delete the todo from the database. When the Not Done button gets clicked, we call the Isdone API to update Isdone in the database.

Item component in the fresh framework

import { useState } from "preact/hooks";

// import Notification from components
import Notification from "../components/Notification.tsx";

interface todo {
    id: string;
    title: string;
    isDone: boolean
}


export default function Item({ item }) {

    // todo
    const [todo, setTodoID] = useState(
        {
            id: item.id,
            title: item.title,
            uuid: item.uuid
        }
    );

    // show Notification based on success
    const [successful, setSuccessful] = useState(false);

    //  delete dfunction
    function deleteItem() {

        if (todo.id) {
            //  call delete api
            fetch(`/api/delete?todoID=${encodeURIComponent(todo.id)}`)
                .then((res) => res.json())
                .then((data) => {
                    console.log("your data submit sucessfully ");
                    setSuccessful(true)
                });
        }
    }


    // isdone
    function isDone() {

        if (todo.id) {
            //  call isdone api
            fetch(`/api/isdone?todoID=${encodeURIComponent(todo.id)}&todoTitle=${encodeURIComponent(todo.title)}&todoUuid=${encodeURIComponent(todo.uuid)}`)
                .then((res) => res.json())
                .then((data) => {
                    console.log("your data submit sucessfully ");
                    setSuccessful(true)
                });
        }
    }

    return (
        <>

            <Notification successful={successful} setSuccessful={setSuccessful} />

            <div class="flex mb-4 items-center">
                <p class={`${item.isDone === false ? "w-full text-green-500 cursor-pointer" : " w-full line-through decoration-purple-600 text-green-500 cursor-pointer"}`}>{item.title}p>
                <button onClick={isDone} class="flex-shrink p-2 ml-4 mr-2 border-2 rounded hover:text-white text-gray-500 border-gray-500 hover:bg-gray-500 w-32">
                    {item.isDone === true ? "Done" : " Not done"}
                button>
                <button onClick={deleteItem} class="flex-shrink p-2 ml-2 border-2 rounded text-red-500 border-red-500 hover:text-white hover:bg-red-500 w-24">Removebutton>
            div>
        
    );
}

And there you have it - we've implemented all our functionality in our Todo app.

Conclusion

SurrealDB is a helpful database, and I hope you enjoyed learning about it in this tutorial.

There are often a lot of requirements to start working with other databases, but SurrealDB is very simple. You need one command to start the database locally and work with it. It is a new revolution in databases.

The big problem is that SurrealDB is not clear on whether it comes with production capabilities. As of right now, it doesn't seem to fulfill the one-click production-ready web app (like MongoDB Atlas, for example).

You can deploy SurrealDB with a Docker image. The problem is that documents are sometimes not enough info for a new developer (for example, how to change passwords and users in a Docker container).

Without cloud Infrastructure, you would not be able to deploy the application with SuurealDB. So for that reason, I did not provide a live demo of the Todo app. But I know that in the future, SuurealDB will change the future of databases.

How to Create a Static Markdown Blog with Deno and Deploy It

Rajdeep Singh — Tue, 13 Sep 2022 16:46:28 +0000

Deno is a runtime for JavaScript and TypeScript. The creator of Node.js built it, and while Node is built with C and C++, Deno is built with the Rust language.

You might be wondering what some of the main differences between Node and Deno are. Well, Rust is a low-level language similar to C and Java. It helps make Deno super fast, and Deno is also more secure than Node.

In this article, we will build a static markdown blog with Deno in less than five minutes. In the end, we'll deploy the markdown blog with Deno deploy.

We'll use Deno's third-party blog package created by Ryan Dahl and another contributor for the blog

With the Deno blog module, you can create a fantastic blazing-fast blog. Then you can set up and deploy the blog with two lines of code. And it takes less than five minutes to configure it.

What is markdown?

Markdown is a lightweight markup language. It helps create consistently formatted text. To start working in markdown, you need an IDE that supports markdown and you'll need to create a file with a .md extension. Markdown typically supports written documents, blogs, and so on.

Some examples of documents written in Markdown are GitHub and npm READMEs, the React.js, and many more.

The Deno blog module (Package) comes with markdown support and lets you create a static blog. This module comes with lots of features, like:

Markdown support.
Auto refresh. Any change in a markdown file automatically builds and reloads your website in the browser.
You can customize the header and add comments and a footer section.
It supports SEO, SEO markup, and an inbuilt feed (sitemap).
iFrames support with markdown files.
It has built-in Preact, TypeScript, and Tailwind CSS support.
It allows multiple authors
It has middleware and redirects pathname support
It comes with server-side Google Analytics support

Here's a demo of the blog we'll build and deploy:

deno blog demo

All the code is available on GitHub.

Here are the steps we'll follow:

How to install and setup the blog
How to understand the folder structure
How to start the local developer server
How to add more configuration to the blog.
How to deploy with Deno

How to Install and Setup the Blog

First, you'll need to install the Deno blog module. The blog module comes with the init command to create a new blog setup. It looks like this:

deno run -r --allow-read --allow-write https://deno.land/x/blog/init.ts my-deno-demo-blog-name

Create a blog setup with the deno blog module

How to Understand the Folder Structure

The beauty of Deno is that you only need a few files to start a project. For the markdown blog, you need only four files:

deno folder structure

Let's go through each file in the above folder structure:

In the deno.jsonc file you add tasks and the importMap file. Tasks are similar to scripts in Node, and in the importMap section, you pass a JSON file that contains all your import packages from Deno.
The import_map.json file contains imports of all packages which you need to run your project.
The posts folder contains all markdown files.
The main.tsx file contains all configurations for the blog module.

How to Start the Local Developer Server

After installation is complete, run the local development server with the deno task dev command.

Run deno local development server

How to Add More Configuration to the Blog

The blog module default comes with the following configuration in the main.tsx file. You can easily change blog configurations according to your requirements.

// main.tsx

import blog, { ga, redirects, h } from "blog";

blog({
  title: "My Blog",
  description: "This is my new blog.",
  // header: Your custom header
,
  // section: Your custom section
,
  // footer: Your custom footer
,
  avatar: "https://deno-avatar.deno.dev/avatar/blog.svg",
  avatarClass: "rounded-full",
  author: "An author",

  // middlewares: [

    // If you want to set up Google Analytics, paste your GA key here.
    // ga("UA-XXXXXXXX-X"),

    // If you want to provide some redirections, you can specify them here,
    // pathname specified in a key will redirect to pathname in the value.
    // redirects({
    //  "/hello_world.html": "/hello_world",
    // }),

  // ]
});

Custom configuration

Demo of custom configuration

With custom configuration, you can make your website look however you want – even like the example above. In addition, you can quickly add more custom configurations to your blog.

For example, you can change the default header, footer, title, author, theme, custom style, links, section, and so on. Here's some code to do that:

// main.tsx

/** @jsx h */
import blog, { h } from "blog";
import { Section } from './components/Section.jsx';

blog({
  author: "Rajdeep singh",
  title: "Hello, my name is Rajdeep Singh",
  description: "Nice to meet you",
  avatar:"assets/logos/profile.jpg",
  avatarClass: "rounded-full",
  coverTextColor:"white",
  links: [
    { title: "Email", url: "mailto:officialrajdeepsingh@gmail.com" },
    { title: "GitHub", url: "https://github.com/officialrajdeepsingh" },
    { title: "Twitter", url: "https://twitter.com/Official_R_deep" },
    { title: "Linkedin", url: "https://www.linkedin.com/in/officalrajdeepsingh/" },
  ],
  lang: "en",
  favicon: "favicon.ico",
  section: <Section/>,
  theme:"auto",
  cover:"assets/logos/backgroundbanner.png",
  ogImage: {
    url: "http://localhost:8000/assets/logos/Frame.png",
    twitterCard:  "summary_large_image" 
  },
  style:".markdown-body ul, .markdown-body ol { list-style: disc !important;}"
});

Markdown files support various types of frontMatter. The most common and widely used fontMatter types are:

YAML: YAML is identified by opening and closing ---.
JSON: JSON is identified by '{' and '}'.
TOML: TOML is identified by opening and closing +++.

The most common frontMatter is YAML. The YAML frontMatter support markdown file is everywhere. But the Deno blog module only supports yml frontMatter.

yml front matter example

The Markdown file is divided into two sections. The first section is the header (frontMatter), and the second is the body section.

The header section contains all metadata for the article. All the metadata is written inside three dashes (---) both opening and closing – for example, post title, tag, description, publish date, and so on.

Finally, in the body section, you write your article body and explain it.

// hello-world.md

---
author : "Rajdeep Singh"
publish_date : "2020-11-10T11:42:46Z"
description : "Easy Ways Add CSS in Next.js #SeriesPart2"
og:image : "assets/images/next.js-add-css-code.jpg"
tags : ["Next.js", "Next", "Next.js Framework", "Next.js Tutorial", "React.js", "react.js tutorial"]
title : "How To Add CSS In Next js?"
allow_iframes: true
cover_html: <img src="assets/images/next.js-add-css-code.jpg" alt="How To Add CSS In Next js" />
pathname: "hello-world"
---

First blog post created with the Deno blog package. It is an amazing package you can use to create markdown blogs with Tailwind CSS. 

<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/3NR9Spj0DmQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen>iframe>


```javascript
console.log("hello world")


The Deno blog module supports the following YML FrontMatter fields in a markdown file:

1. author (string): The `author` contains the names of the authors. For example, `author : "Rajdeep singh , deno"`
2. publish_date(Date):  The `publish_date` is required for the article.
3. description (string): The `description` is required for the description.
4. og:image(string): The `og:image` is not required. It is used for ``
5. tags(string[]): The `tags` are just keywords used for SEO. They're not compulsory.
6. title(string): The `title` is required for the heading.
7. allow_iframes( boolean ): the `allow_iframes` allows you to use `iframe` HTML.
8. pathname( string ): pathname is not required. For example, `http://yourdomain.com/hello-world` after your domain `hello-world` is your pathname
9. cover_html(string): The `cover_html` contains the HTML for the blog.

author : "Rajdeep Singh , Rajvinder singh" publish_date : "2022-03-20T13:09:24Z" description : "Npm install command help to install package from npmjs.org" og:image : "assets/images/npm-init-command-1.png" tags : ["npm-test", "npm-cli", "npm install command"] title : "What is the npm install command?" allow_iframes: true pathname:"/how-is-npm-install-command" cover_html:


These are all the supported fields by YML frontMatter for markdown files:

title, author, publish_date, description, og:image, tags, allow_iframes, pathname, cover_html


This is the required field for markdown files:

title ```

Without a title filed, the blog module produces an error Uncaught TypeError: Cannot read properties of undefined (reading 'snippet').

Error: Uncaught TypeError: Cannot read properties of undefined (reading 'snippet')

How to Deploy Your Blog with Deno

The final step is to deploy our static blog in Deno. Currently, the Deno blog module only supports Deno for deployment. But Deno deploy provides a similar interface to Netlify and Vercel. So you can easily understand the dashboard if you've worked with those tools before.

To deploy a new blog on Deno, you need two things. The first is an account on Deno deploy, and the second is a GitHub account. With a GitHub repository to help manage your articles, it is a straightforward process similar to Vercel and Netlify.

Deployment steps:

Here are the steps to deploy your blog with Deno deploy (we'll go through each one in detail below):

First, login to your account on Deno deploy
Click to create a new project
Configure the GitHub repository and environment variables
Deploy the static blog

First, go to the Deno deploy website and create a new account if you don't have one already. If you do, then login to your account.

deno deploy website

Click to create a new project

After successfully logging in, you can now access the Deno dashboard and click on the "+ new project" button.

Create a new project with deno deploy

Configure the GitHub repository and environment variables

After clicking on the new project button, you'll be redirected to the project configuration page. Your project page will look like the below. Just fill in all the details:

Fill out your new project configuration and link to GitHub

The first time click the GitHub button. After that, Deno deploys and asks for permission for a GitHub account. After granting all the permissions, your project page looks like this:

After finishing the information

After opening the project page, you fill in all the required information.
Then, in the second step, select the GitHub repository.
After selecting the GitHub repository, select a branch, then choose main.tsx file.
Give any project name, but make sure you name is in lowercase letters – for example, my-new-website. Otherwise, you'll get a capital case error.
Click on the environment variable and add an environment (if you have one - otherwise, skip it).

And that's it - you've done all the configuration successfully. Now click on the link button.

Deployment is finished

After deployment is finished, you'll see the website dashboard. Click on the view button to view your production-ready website.

Your website dashboard with deno looks like this after successful website deployment.

Here's a tip to help you manage all your markdown files and speed up your written work. The VS Code code editor has a free, open-source FrontMatter VS Code extension. It's a great tool to manage all your markdown files inside VS Code with the FrontMatter dashboard.

Manage markdown files with VS Code extension

Conclusion

The Deno blog module is an excellent library for creating a personal blog in five minutes and deploying it with Deno. Deno deployment is speedy. It takes less than ten seconds.

I think the Deno blog module is best for personal use because you do not need to customize many things. You only customize the header, footer, and various sections.

Thank you for reading!

References to help you setup your blog:

Intro to Deno – Guide for Beginners

Brian Barrow — Fri, 09 Sep 2022 22:50:17 +0000

What is Deno?

Deno is a new JavaScript runtime. It was built by Ryan Dahl, the creator of Node.js.

Dahl had a few things that he regretted doing with Node and wanted to build a runtime that could solve those issues. Deno, like Node, is built on the V8 JavaScript engine but was built using Rust instead of C++.

One of the main goals of Deno is to bring server side JavaScript closer to browser JavaScript.

If you've written in both Node and browser JavaScript, then you have surely run into the differences in the APIs used in the respective spaces. Deno aims to have the same APIs on the server that you would use in the browser. We'll take a deeper look at specific examples of this later on.

Key Features of Deno

Deno Uses TypeScript

One of the most eye catching features of Deno is that it treats TypeScript as a first class language out of the box. This means you can run or use TypeScript without installing any other external or third party packages. It just works.

TypeScript is increasingly popular in the JavaScript world, and lots of tools and companies are pushing towards using it. It is cool to see a new progressive technology like TypeScript get more attention, and getting first class status in a big project like Deno is a huge step forward.

Deno is Secure by Default

Deno by default is secure. This means that unless the script is specifically allowed, it cannot access system files, the environment (things like environment variables), or the network.

In order to specifically allow for access to these features, you need to pass the respective flag in the CLI command. Here are some of the ones you'll use the most:

Network access: --allow-net, you can also specify which URLs the code is allowed to access. For example: --allow-net=https://api.deepgram.com
File access: --allow-read
Environment access: --allow-env

Deno's Browser Compatibility

Like I mentioned above, Deno strives to have the same API as the browser. The biggest of these in my opinion is the support of the fetch API.

These days, in most of the JavaScript I write, I use the fetch API. Being able to use the same syntax on my server side code makes it a lot easier to be productive and it makes the load of context switching much smaller.

Package Manager

Deno doesn't have a package manager registry. Node uses npm in order to load third party packages into your project, but Deno loads modules via URLs.

I was honestly confused at first by this. Having "grown up" with Node and npm it was weird to me to not have some sort of package manager or package.json file.

Instead of this centralized registry, Deno allows package developers to host their code wherever they want. If the code is hosted on GitHub, you can register your module on their hosting service where it is cached. That makes it easier for developers to find and use the module.

ES Modules

Deno also uses ES Modules and does not support the require() syntax. Again, most of the JavaScript I write these days uses modern features like this, so it has been nice to not worry about making sure I'm using the correct syntax depending on which environment I'm coding for.

Standard Library

Deno ships with a standard library that contains functionality that is audited by the Deno team. This makes it really easy to get started using Deno.

There is no need to look to third party packages to do fairly basic things that are needed in server side code. As a developer, it is comforting knowing that the code I use is officially supported and approved by the Deno team.

Testing module

One of the modules included in the standard library is the testing module. This module makes writing tests easier in Deno and will make them more consistent across projects.

This might not be a plus for everyone, especially if some have strong opinions on testing libraries. I really like it though. As Deno continues to grow, consistency across projects will make maintaining code and switching projects much easier.

Deno vs Node

The biggest question surrounding Deno is how it compares to Node.

Deno clearly offers some advantages over Node. Being secure by default is definitely an attractive feature, and developers will see the out of the box support for TypeScript as a big win.

On the other hand, Node has a very rich community with an established ecosystem and third party packages that make it easier to get up and running. With the announcement that Deno will support most npm packages I can see people moving over to Deno sooner rather than later.

Deno also recently released Deno Deploy to public beta. This will allow users to rapidly deploy JavaScript code at the edge. This service might give the Deno company an edge (pun intended) over time and grow the user-base.

Conclusion

The experience I've had with Deno over the last several months has been a lot of fun. I've enjoyed working with it and am excited to see what the future brings for it.

Over the next few weeks I'll be writing several posts diving deeper into the Deno world.

How to Build React Applications with Deno Using the AlephJS Library

Akash Joshi — Fri, 12 Mar 2021 18:08:00 +0000

If you're a front end developer who's just getting started with Deno, you might be wondering – can you build something as complex as a NextJS or create-react-app (CRA) application using Deno?

I was recently thinking the same thing. I wanted to try Deno because of its shareability that results from being able to run an application directly from a URL. The Deno compiler supports running JavaScript and TypeScript files from a URL and it also supports imports from a URL, resulting in extreme portability.

I looked to see if there were any existing solutions online, but I only found this article, which built an SSR'd React application using some complex techniques. It wasn't simple, like getting started with NextJS or CRA.

So, through my searches online, I ended up at AlephJS, which has one of the coolest landing page animations ever.

Aleph is a Zero-Config, Typescript-driven React framework, just like NextJS. The only drawback is that that Aleph is still very much in alpha.

So to get a true Next-like React experience inside Deno, let's get started with AlephJS. It has many of the same conventions as Next, such as:

A /pages directory for creating URL routes
Direct .js, .jsx, .ts, .tsx support in pages
A /public directory for serving static assets like video, audio, or image files
A /pages/api folder for serving JavaScript or TypeScript files as serverless APIs.

If you want to watch a video about how to do this to supplement your reading, check it out here:

How to Get Started with AlephJS

To be able to use AlephJS, you need Deno installed on your machine. You can see how to install and get started with Deno in my previous article here.

To get started with Aleph, you need to first install the Aleph CLI by running this command:

deno install -A -f -n aleph https://deno.land/x/aleph@v0.3.0-alpha.1/cli.ts

After installation, you can run aleph -h to check whether it got installed correctly.

Because of the portability of Deno, you can replace aleph with deno run -A https://deno.land/x/aleph@v0.3.0-alpha.1/cli.ts start $app_URI for any command and it will be able to run the Aleph program without having the CLI locally installed.

To create a starter app, run:

aleph init hello
cd hello

And start the app in development mode using aleph dev to start a server at port 8080.

To start the app in production mode, you have to first build the app and then run the built app. You can do this through these commands:

aleph build # build your app
aleph start # runs built app

After you initialise your Aleph app, you will find that the root component is defined at pages/index.tsx. It's a normal React component. You can experiment with it to see how Aleph works.

You can add more routes to your application by creating more .jsx or .tsx files inside the pages folder. You can read more on routing in Aleph here.

How to Import Libraries in Deno

I've written about Deno previously on freeCodeCamp where I demoed some Deno basics, including URL imports. Since Aleph is a Deno framework, all imports happen in the "Deno way".

There are two kinds of libraries which you can import in a Deno application.

Importing Deno-Native Libraries: These libraries were either built for Deno, or ported over from npm to support Deno usage.
Importing from NPM: if you've worked with JS recently you probably know about npm. If you don't, npm (the company behind node package manager) is the standard repository for all JavaScript libraries. Luckily, Deno has limited support for npm libraries. Using tools like esm.sh or skypack.dev, users can import npm libraries into Deno.

1. How to Import Deno-Native Libraries

You can import Deno-Native libraries in your application by importing their URLs directly. You can find a list of Deno libraries here: deno.land/x

To test this out, let’s import this standard Deno date formatting library, and call a date format function in a React page. Create a file date-import.tsx in the pages folder of your app. Inside the file, write the following code:

// react is a compulsoy import in Aleph
import React from "react";

// import the format function from its URL
import { format } from "https://deno.land/std@0.88.0/datetime/mod.ts";

// capitalize the function name so it's recognized as a React component
export default function DateImport() {
    // Here, directly calling the format function works as expected.
  return <section>Hello all! Today is: {format(new Date(), "dd-MM-yyyy")}section>;
}

To see the output of this file, go to localhost:8080/date-import, or its equivalent for your server. You should see the page displaying today's date.

2. How to Import Libraries from NPM

To import an npm library, you can also import directly from a URL – but in this case there's a slight change. Since we talked about esm.sh and skypack.dev, let's try to use them in action. In this case, let's try to use the dayjs library in our project.

Note: Not all npm libraries work correctly in Deno because they may be relying on Node-specific functions.

To import a library in esm.sh, you post-pend the library's package name to the URL. In this case to import dayjs, we would be importing https://esm.sh/dayjs. This also works for any CSS files you might want to import from a library.

Now, let's create a file in pages called dayjs-import.tsx. So, the code in our page will look like this:

// react is a compulsoy import in Aleph
import React from "react";

// import the dayjs npm library using esm.sh
import dayjs from "https://esm.sh/dayjs";

// capitalize the function name so it's recognized as a React component
export default function DateImport() {
    // call the dayjs function directly to display today's date
  return <section>Hello all! Today is: {dayjs().format("DD-MM-YYYY")}section>;
}

To see the output of this file, go to localhost:8080/dayjs-import, or its equivalent for your server. You should see the page displaying the day's date.

There's one important thing before we go ahead, though – how do you handle React imports like importing useState, useEffect, and so on? Luckily, the devs at Aleph have already written an example for us.

Go into ./lib/useCounter.ts and you'll find the code for the custom hook that's used for the counter in the home page.

Since I want to focus on Aleph and React themselves in this article, to check out all the different ways you can import a CSS file in Aleph, visit this page from the official documentation.

How to Build a Sample App with Deno and AlephJS

Now, let's get into the nitty gritty and try to build a React app in Aleph ourselves. We're going to be building "Is It Down?", a sample app I had made using an existing website-checking API. This app will allow us to check whether a website is currently up or down.

Here's the CodeSandbox link: https://codesandbox.io/s/awesome-firefly-5dofg

Building this application will show you how to use the State hook, the Effect hook, and how to make API calls in Aleph.

Create a new file called web-checker.tsx in your pages folder. Let's start by just adding the UI elements first. We'll display an h1 element with the title, an h2 element linking to the API, and a form element to take user input. This is a non-interactive page that just displays the elements.

import React from "react";

export default function App() {
    return (
    <div style={{ fontFamily: "sans-serif", textAlign: "center" }}>
      <h1>Is it Down?h1>
      <h2>
        Go{" "}
        <a
          href="https://rapidapi.com/jakash1997/api/website-data-gathering-and-update-tracking"
          target="_blank"
        >
          here
        a>{" "}
        to get an API key
      h2>

      <form
        onSubmit={(e) => {
          e.preventDefault();
        }}
      >
        <input
          type="text"
        />
        <button type="submit">Submitbutton>
      form>
    div>
  );
}

Next, to capture the state of the input field, and also to capture the response of the API call we will have to make, let's introduce state.

// import useState from react
import React, { useState } from "react";

export default function App() {
  // define both state variables
  const [siteURL, setUrl] = useState("");
  const [response, setResponse] = useState(undefined);
...

Now, we'll use this state inside our input element so it can react to it.

...
(e) => setUrl(e.target.value)}
  type="text"
/>
...

We'll also add some code to display a response when it's returned from the API response:

...
    

    <br />

    <code>{JSON.stringify(response, null, 2)}code>

...

Now, to get started with integrating the API, let's try to form the request correctly. In this case, the API is a simple GET call, so we only need to pass a param and an API key.

Firstly, go here, and generate an API key: https://rapidapi.com/jakash1997/api/website-data-gathering-and-update-tracking. Find the API key like you see in the screenshot below, and keep it somewhere safe:

Next, let's create a separate function submitData which will generate the required request data. We will be using the axios library to make our GET call, so we will be forming its options object.

...
const [response, setResponse] = useState(undefined);

const submitData = (siteURL) => {
  setResponse("Loading...");
  const options = {
        // passing siteURL here through object shorthand
    params: { siteURL },

        // passing the required headers here
    headers: {
      "x-rapidapi-key": "YOUR_API_KEY",
      "x-rapidapi-host":
        "website-data-gathering-and-update-tracking.p.rapidapi.com",
    },
  };

    // print options here
    console.log("options", options);
};

return (
...

And we add this to the onSubmit function in our form.

onSubmit={(e) => {
  e.preventDefault();
  submitData(siteURL);
}}

Now, whenever you press the Submit button, you will see the options we generated in the console. If you see the options object in the console, you're doing well so far!

Next we just have the simple step of importing the axios library using http://esm.sh and using it to make an API call.

Import axios after the react import like this:

import React, { useState } from "react";
import axios from "https://esm.sh/axios";

...

And use it in the submitData function as:

...
    axios
    .get(
      "https://website-data-gathering-and-update-tracking.p.rapidapi.com/sitecheck",
      options
    )
    .then(function (response) {
      setResponse(response.data);
      console.log(response.data);
    })
    .catch(function (error) {
      console.error(error);
    });
};
...

And that's it! Try submitting the form again, and this time you'll see the result both on screen and in the console.

Conclusion

Now you know the basics of Aleph. It's a really interesting tool which allows you to mix your existing React knowledge with the forward-looking nature and security of deno.land.

If you liked this tutorial, you can follow me on Twitter @thewritingdev.

How to Build a URL Shortener in Deno

Akash Joshi — Wed, 07 Oct 2020 15:40:28 +0000

In this article, we’re going to learn the basics of Deno, like how to run a program and embrace security.

Deno is the new JavaScript and TypeScript runtime written in Rust. It offers tight security, TypeScript support out-of-the-box, a single executable to run it, and a set of reviewed and audited standard modules.

Like npm in Node.js, packages in Deno are managed in a centralized package repository called X. We'll be using one of these libraries, Oak, to build a REST API-based server in Deno.

After learning the basics by using the Express-like router package Oak, we will jump into the deep end of Deno and build a complete application.

Here's what we will set up in this application:

Mapping URL shortcodes to endpoints using a JSON-based config file.
Have expiration dates attached to each URL so that these redirects are only valid for a limited period of time.

0. Prerequisites

Install Deno from this link.
Make sure you know the basics of JavaScript.

Although not really required to follow along with this article, you can check out the YouTube video below to get an intro to Deno in video-format.

So, let’s get started. ?

1. How to Build the Router

To write the server-side code for our application, we'll use the Oak module. It has an Express-like syntax for defining API routes.

If we look at its documentation here, the "Basic Usage" section pretty much covers all the use cases we will need in our router. So, we will expand on that code to build our application.

To test this code, you can create a file called index.ts in a folder, and copy the "Basic Usage" code into it.

To understand how to run TypeScript or JavaScript files in Deno, you first need to understand how Deno runs files.

You run a file by running the command deno run file_name.ts or file_name.js, followed by a set of flags providing certain system permissions to your application.

To test this, run the file we just created, containing the "Basic Usage" code, by using the command deno run index.ts.

You will see that Deno complains that you haven't given network access to your application. So, to do that, you add the -allow-net to the run command. The command will look like deno run index.ts -allow-net.

The router written down in the "Basic Usage” code looks like this:

router
  .get("/", (context) => {
    context.response.body = "Hello world!";
  })
  .get("/book", (context) => {
    context.response.body = Array.from(books.values());
  })
  .get("/book/:id", (context) => {
    if (context.params && context.params.id && books.has(context.params.id)) {
      context.response.body = books.get(context.params.id);
    }
  });

To break down the above code, first a router object has been defined. Then the get function is called on the router, to define the various endpoints for our application. The respective logic is defined inside the callback functions.

For example, for the "/" endpoint, a callback function which returns "Hello World" in the response body has been defined. We can keep this endpoint unchanged to test whether our application server is running by receiving this response.

We don’t need the “/book” URL which has been defined, so its definition can be safely removed. At this point, your router should have the below structure:

router
  .get("/", (context) => {
    context.response.body = "Hello world!";
  })
  .get("/book/:id", (context) => {
    if (context.params && context.params.id && books.has(context.params.id)) {
      context.response.body = books.get(context.params.id);
    }
  });

In the next section, we'll be focussing on starting to build the actual application.

2. How to Build the URL Shortener

Now let's get started with building the actual URL shortener.

It should redirect to a destination (dest), based on a shortcode. The redirect should also only be valid up to an expiryDate, which can be provided in the Year-Month-Day format.

Based on these assumptions, let's create the config file, named urls.json. The format of the file will be:

{
  "shortcode": {
    "dest": "destination_url_string",
    "expiryDate": "YYYY-MM-DD"
  }
}

You can check out the JSON file here.

To read this JSON file in your code, add the following to the top of your index.ts:

import { Application, Router } from "";

const urls = JSON.parse(Deno.readTextFileSync("./urls.json"));

console.log(urls);

Now, to run your index.ts, you will need another flag —allow-read, otherwise Deno will throw a "read permissions not provided" error. Your final command becomes deno run —allow-net —allow-read index.ts.

After running this command, you'll see the JSON file being printed in your terminal window. This means that your program is able to read the JSON file correctly.

If we go back to the "Basic Usage" example that we saw above, the route “/book/:id” is exactly what we need.

Instead of "/book/:id", we can use "/shrt/:urlid", where we will get the individual URLs based on the URL ID (:urlid).

Replace the existing code present inside the "/book/:id" route with this:

.get("/shrt/:urlid", (context) => {
    if (context.params && context.params.urlid && urls[context.params.urlid]) {
      context.response.redirect(urls[context.params.urlid].dest);
    } else {
      context.response.body = "404";
    }
  });

The if condition in the route does the following:

Checks if parameters are attached to the route
Checks if the parameter urlid is in the parameter list.
Checks whether the urlid matches with any URL in our JSON.

If it matches with all these, the user is redirected to the correct URL. If it doesn't, a 404 response on the body is returned.

To test this, copy this route into index.ts. The router will now look like this:

router
  .get("/", (context) => {
    context.response.body = "Hello world!";
  })
    .get("/shrt/:urlid", (context) => {
        if (context.params && context.params.urlid && urls[context.params.urlid]) {
          context.response.redirect(urls[context.params.urlid].dest);
        } else {
          context.response.body = "404";
        }
      });

And run the file using deno run —allow-net —allow-read index.ts.

If you copied the JSON file from the example, and if you go to http://localhost:8000/shrt/g, you'll be redirected to Google's homepage.

On the other hand, if you use a random shortcode that doesn't work in our URL's config, it brings you to the 404 page.

However, you'll see that our shortener doesn't react live to changes in the JSON file. To test this, try adding a new redirect to urls.json in the same format as:

"shortcode": {
    "dest": "destination_url_string",
    "expiryDate": "YYYY-MM-DD"
  }

The reason for this is that urls.json is only read once at that start. So, now we will add live-reloading to our server.

3. How to Add Live-Reloading

To make the urls object react live to changes in the JSON file, we simply move the read statement inside our route. This should look like the following:

.get("/shrt/:urlid", (context) => {
  const urls = JSON.parse(Deno.readTextFileSync("./urls.json"));

  if (context.params && context.params.urlid && urls[context.params.urlid]) {
    context.response.redirect(urls[context.params.urlid].dest);
  } else {
    context.response.body = "404";
  }
});

Note how we have moved the URLs object inside our router. Now in this case, the config file is read every time that route is called, so it can react live to any changes made in the urls.json file. So even if we add or remove other redirects on the fly, our code reacts to it.

4. How to Add an Expiration to the URLs

To make our URLs expire at a certain date, we will be using the popular Moment.js library, which makes it easy to work with dates.

Luckily, it has also been ported for Deno. To understand how it works, check out its documentation in the previous link.

To use it in our code, import it directly through its URL like this:

import { Application, Router } from "";
import { moment } from "";

const router = new Router();

To check the date for when the URL will expire, we check the expiryDate key on our urls object. This will make the code look like this:

if (context.params && context.params.urlid && urls[context.params.urlid]) {
  if (
    urls[context.params.urlid].expiryDate > moment().format("YYYY-MM-DD")
  ) {
    context.response.redirect(urls[context.params.urlid].dest);
  } else {
    context.response.body = "Link Expired";
  }
} else {
  context.response.body = "404";
}

In moment().format("YYYY-MM-DD"), we get the current date and time using moment(). We can convert it to the "YYYY-MM-DD" (Year-Month-Date) format using the function .format("YYYY-MM-DD").

By comparing it against our expiryDate key, we can check whether the URL has expired or not.

That's it! You have built a fully functional URL shortener in Deno. You can find the final code in the GitHub repo here.

Test it out by setting expiryDate as the current date and by making other changes to urls.json and our code.

My Thoughts on Deno

To wrap the article up, I'll put my forward final thoughts on deno.land.

While it's refreshing to see a server-side language which takes security into consideration and supports TypeScript out-of-the-box, Deno still has a long way to go before being ready for use in production systems.

For example, the TypeScript compilation is still very slow, with compilation times ~20 seconds, even for simple programs like the one we just developed.

On the error-reporting front, it still is pretty bad with describing the errors. For example, while embedding the code to read urls.json in the function itself, Deno isn't able to report that the -allow-read flag hasn't been set. Instead, it just throws an internal server error without a proper error printed on the terminal.

What Next?

You can improve your Deno or Typescript skills by building more complex applications like a Chatting Application or a Wikipedia Clone.

You can also go through the Deno documentation at deno.land to get more familiar with the basics.

Thank you for reading this far and happy programming ? !!

Important Links

Deno - https://deno.land
Deno X (package repository) - https://deno.land/x/
Oak (REST framework) - https://deno.land/x/oak
Oak Basic Usage - https://deno.land/x/oak@v6.3.1#basic-usage
Final GitHub Repo - https://github.com/akash-joshi/deno-url-shortener

Learn Deno, a Node.js alternative

Beau Carnes — Tue, 30 Jun 2020 17:08:13 +0000

Deno is a Node.js alternative created by Ryan Dahl, the same person who created Node.js.

Many people, including Ryan Dahl, think that Deno is superiod to Node.js. We've posted a 6-hour video course all about Deno on the freeCodeCamp.org YouTube channel. Decide for yourself if it is better than Node.

You will learn the basics of Deno in the course. Deno can be used with JavaScript or TypeScript, but it is more common to use TypeScript. This course includes a mini crash-course on TypeScript.

This course was created by The Codeholic. By the end of the course, you will have used Deno to build a survey app with a REST API using MongoDB. Then you will be ready to start implementing your own applications based on Deno.

Here are the things covered in the course:

What is Deno?
How to install
"Hello World" in Deno
Deno commands
TypeScript basics
Main Demo features
Deno standard library
Third party libraries
Working with the file system
Create a basic HTTP server
Using npm packages
Building a real-world project
Deno best practices

Watch the full course on the freeCodeCamp.org YouTube channel (6 hour watch).

How to Use MySQL With Deno and Oak

freeCodeCamp — Sun, 07 Jun 2020 16:40:17 +0000

By Adeel Imran

I recently wrote about how to make a Todo API in Deno + Oak (without using a database). You can find the repo under chapter_1:oak on GitHub.

This tutorial picks up where the other left off, and I'll go over how to integrate MySQL into a Deno and Oak project.

If at any time you want to see the entire source code used in this tutorial, it's available at chapter_2:mysql. Feel free to give it a star on GitHub if you like it.

I'm assuming that you already completed the last tutorial mentioned above. If not, check it out here and come back when you're finished.

Before we start, make sure that you have a MySQL client installed and running:

MySQL community server [Download here]
MySQL Workbench [Download here]

I wrote a small guide for Mac OS users on setting up MySQL because I struggled with it as well. Check it out here.

If you are on a Windows machine you can use the same tools or you can also use XAMPP to have a MySQL instance running in your dashboard.

Once you have a MySQL instance running we can begin our tutorial.

Let's Begin

Assuming that you're coming from this article, Todo API in Deno + Oak (without using a database), we will do the following:

Create a MySQL database connection
Write a small script that resets the database every time we start our Deno server
Perform CRUD operations on a table
Add the CRUD functionality to our API controllers

One last thing – here is the entire commit difference that was made in Chapter 1 to add MySQL to the project (source code that shows the new additions made from chapter 1).

In your project root folder – mine is called _chapter_2:mysql,_ though yours can be called whatever you want – create a folder called db. Inside that folder, create a file called config.ts and add the following content to it:

export const DATABASE: string = "deno";
export const TABLE = {
  TODO: "todo",
};

Nothing fancy here, just defining our database name along with an object for tables and then exporting it. Our project will have one database called "deno" and inside that db we will only have one table called "todo".

Next, inside the db folder, create another file called client.ts and add the following content:

import { Client } from "https://deno.land/x/mysql/mod.ts";
// config
import { DATABASE, TABLE } from "./config.ts";

const client = await new Client();

client.connect({
  hostname: "127.0.0.1",
  username: "root",
  password: "",
  db: "",
});

export default client;

A couple of things are happening here.

We are importing Client from the mysql library. Client will help us connect to our database and perform operations in the database.

client.connect({
  hostname: "127.0.0.1",
  username: "root",
  password: "",
  db: "",
});

Client provides a method called connect which takes in object where we can provide the hostname, username, password, and db. With this information it can establish a connection to our MySQL instance.

Make sure that your username has no password, as it will conflict with connecting to Deno's MySQL library. If you don't know on how to do that, read this tutorial I wrote.

I have left the database field blank here because I want to select it manually later in my script.

Let's add a script that will initialize a database called "deno", select it, and inside that db create a table called "todo".

Inside db/client.ts file let's make some new additions:

import { Client } from "https://deno.land/x/mysql/mod.ts";
// config
import { DATABASE, TABLE } from "./config.ts";

const client = await new Client();

client.connect({
  hostname: "127.0.0.1",
  username: "root",
  password: "",
  db: "",
});

const run = async () => {
  // create database (if not created before)
  await client.execute(`CREATE DATABASE IF NOT EXISTS ${DATABASE}`);
  // select db
  await client.execute(`USE ${DATABASE}`);

  // delete table if it exists before
  await client.execute(`DROP TABLE IF EXISTS ${TABLE.TODO}`);
  // create table
  await client.execute(`
    CREATE TABLE ${TABLE.TODO} (
        id int(11) NOT NULL AUTO_INCREMENT,
        todo varchar(100) NOT NULL,
        isCompleted boolean NOT NULL default false,
        PRIMARY KEY (id)
    ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
  `);
};

run();

export default client;

Here we are importing DATABASE and TABLE from our config file, then using those values in a new function called run().

Let's break down this run() function. I have added comments in the file to help you understand the workflow:

const run = async () => {
  // create database (if not created before)
  await client.execute(`CREATE DATABASE IF NOT EXISTS ${DATABASE}`);
  // select db
  await client.execute(`USE ${DATABASE}`);

  // delete table if it exists before
  await client.execute(`DROP TABLE IF EXISTS ${TABLE.TODO}`);
  // create table
  await client.execute(`
    CREATE TABLE ${TABLE.TODO} (
        id int(11) NOT NULL AUTO_INCREMENT,
        todo varchar(100) NOT NULL,
        isCompleted boolean NOT NULL default false,
        PRIMARY KEY (id)
    ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
  `);
};

run();

Create a database called deno . If it already exists then do nothing.
Then select the database to use, which is called deno
Delete the table inside deno called todo if it already exists.
Next, create a new table inside the deno db, call it todo, and define its structure: It will have a unique auto increment id which will be an integer, another field called todo which will be a string, and finally a field called isCompleted which is a boolean. I also define id as my primary key.

The reason I wrote this script was because I don't want to have extra information in MySQL instance. Every time the script runs it just reinitializes everything.

You don't have to add this script. But if you don't, then you will have to manually create a db and the table.

Also, check out the Deno MySQL library's docs on db creation and on table creation.

Going back to our agenda, we just achieved two things out of the four mentioned at the top of the article:

Create a MySQL database connection
Write a small script that resets the database every time we start our Deno server

That is already 50% of the tutorial. Unfortunately, we can't see much happening right now. Let's quickly add some functionality to see it working.

Performing CRUD operations on a table and adding the functionality to our API controllers

We need to update our Todo interface first. Go to the interfaces/Todo.ts file and add the following:

export default interface Todo {
  id?: number,
  todo?: string,
  isCompleted?: boolean,
}

What this ? does is it makes the key in the object optional. I did this because later I will use different functions to pass objects with only an id, todo, isCompleted, or all of them at once.

If you want to learn more about optional properties in TypeScript, head over to their docs here.

Next, create a new folder called models and inside that folder, create a file called todo.ts. Add the following content to the file:

import client from "../db/client.ts";
// config
import { TABLE } from "../db/config.ts";
// Interface
import Todo from "../interfaces/Todo.ts";

export default {
  /**
   * Takes in the id params & checks if the todo item exists
   * in the database
   * @param id
   * @returns boolean to tell if an entry of todo exits in table
   */
  doesExistById: async ({ id }: Todo) => {},
  /**
   * Will return all the entries in the todo column
   * @returns array of todos
   */
  getAll: async () => {},
  /**
   * Takes in the id params & returns the todo item found
   * against it.
   * @param id
   * @returns object of todo item
   */
  getById: async ({ id }: Todo) => {},
  /**
   * Adds a new todo item to todo table
   * @param todo
   * @param isCompleted
   */
  add: async (
    { todo, isCompleted }: Todo,
  ) => {},
  /**
   * Updates the content of a single todo item
   * @param id
   * @param todo
   * @param isCompleted
   * @returns integer (count of effect rows)
   */
  updateById: async ({ id, todo, isCompleted }: Todo) => {},
  /**
   * Deletes a todo by ID
   * @param id
   * @returns integer (count of effect rows)
   */
  deleteById: async ({ id }: Todo) => {},
};

Right now the functions are empty, but that is okay. We will fill them up one by one.

Next go to controllers/todo.ts file and make sure you add the following:

// interfaces
import Todo from "../interfaces/Todo.ts";
// models
import TodoModel from "../models/todo.ts";

export default {
  /**
   * @description Get all todos
   * @route GET /todos
   */
  getAllTodos: async ({ response }: { response: any }) => {},
  /**
   * @description Add a new todo
   * @route POST /todos
   */
  createTodo: async (
    { request, response }: { request: any; response: any },
  ) => {},
  /**
   * @description Get todo by id
   * @route GET todos/:id
   */
  getTodoById: async (
    { params, response }: { params: { id: string }; response: any },
  ) => {},
  /**
   * @description Update todo by id
   * @route PUT todos/:id
   */
  updateTodoById: async (
    { params, request, response }: {
      params: { id: string };
      request: any;
      response: any;
    },
  ) => {},
  /**
   * @description Delete todo by id
   * @route DELETE todos/:id
   */
  deleteTodoById: async (
    { params, response }: { params: { id: string }; response: any },
  ) => {},
};

Here we have empty functions as well. Let's start filling them up.

[Get] all todos API

Inside models/todo.ts, add a definition for a function called getAll:

import client from "../db/client.ts";
// config
import { TABLE } from "../db/config.ts";
// Interface
import Todo from "../interfaces/Todo.ts";

export default {
   /**
   * Will return all the entries in the todo column
   * @returns array of todos
   */
  getAll: async () => {
    return await client.query(`SELECT * FROM ${TABLE.TODO}`);
  },
}

The Client also exposes another method besides connect (we used a "connect" method in db/client.ts file) and that is query. The client.query method lets us run MySQL queries directly from our Deno code as is.

Next go to controllers/todo.ts add definition for getAllTodos:

// interfaces
import Todo from "../interfaces/Todo.ts";
// models
import TodoModel from "../models/todo.ts";

export default {
  /**
   * @description Get all todos
   * @route GET /todos
   */
  getAllTodos: async ({ response }: { response: any }) => {
    try {
      const data = await TodoModel.getAll();
      response.status = 200;
      response.body = {
        success: true,
        data,
      };
    } catch (error) {
      response.status = 400;
      response.body = {
        success: false,
        message: `Error: ${error}`,
      };
    }
  },
}

All we are doing is importing TodoModel and using its method called getAll, which we just defined now. Since it returns as a promise we have wrapped it in async/await.

The method TodoModel.getAll() will return us an array which we simply return to response.body with status set to 200.

If the promise fails or there is another error, we simply go to our catch block and return a status of 400 with success set to false. We also set the message to what we get from the catch block.

That's it, we're done. Now let's fire up our terminal.

Make sure your MySQL instance is running. In your terminal type:

$ deno run --allow-net server.ts

Your terminal should look something like this:

This is how my console looks when I start the server

My console is telling me two things here.

That my Deno API server is running on port 8080
That my MySQL instance is running on 127.0.0.1, which is localhost

Let's test our API out. I am using Postman here, but you can use your favorite API client.

running [GET] localhost:8080/todos => Will return all todos

Right now it only returns empty data. But once we add data to our todo table, it will return those todos here.

Awesome. One API down and four more to go.

[Post] add a todo API

In the models/todo.ts file, add the following definition for add() function:

export default {
   /**
   * Adds a new todo item to todo table
   * @param todo
   * @param isCompleted
   */
  add: async (
    { todo, isCompleted }: Todo,
  ) => {
    return await client.query(
      `INSERT INTO ${TABLE.TODO}(todo, isCompleted) values(?, ?)`,
      [
        todo,
        isCompleted,
      ],
    );
  },
}

The add function takes in object as an argument, which has two items: todo and isCompleted.

So _add_: _async_ ({ todo, isCompleted }: Todo) => {} can also be written as ({todo, isCompleted}: {todo:string, isCompleted:boolean}). But since we already have an interface defined in our interfaces/Todo.ts file which is

export default interface Todo {
  id?: number,
  todo?: string,
  isCompleted?: boolean,
}

we can simply write this as _add_: _async_ ({ todo, isCompleted }: Todo) => {}. This tells TypeScript that this function has two arguments, todo, which is a string, and isCompleted, which is a boolean.

If you want to read more on interfaces, TypeScript has an excellent document on it which you can find here.

Inside our function we have the following:

return await client.query(
  `INSERT INTO ${TABLE.TODO}(todo, isCompleted) values(?, ?)`,
  [
    todo,
    isCompleted,
  ],
);

This query can be broken down into two parts:

INSERT INTO ${TABLE_._TODO}(todo, isCompleted) values(?, ?). The two question marks here denote a use of variables inside this query.
The other part, [todo, isCompleted], is the variables that will go in the first part of the query and be replaced with (?, ?)
Table.Todo is just a string coming from file db/config.ts where the Table.Todo value is "todo"

Next inside our controllers/todo.ts file, go to the definition of the createTodo() function:

export default {
   /**
   * @description Add a new todo
   * @route POST /todos
   */
  createTodo: async (
    { request, response }: { request: any; response: any },
  ) => {
    const body = await request.body();
    if (!request.hasBody) {
      response.status = 400;
      response.body = {
        success: false,
        message: "No data provided",
      };
      return;
    }

    try {
      await TodoModel.add(
        { todo: body.value.todo, isCompleted: false },
      );
      response.body = {
        success: true,
        message: "The record was added successfully",
      };
    } catch (error) {
      response.status = 400;
      response.body = {
        success: false,
        message: `Error: ${error}`,
      };
    }
  },
}

Let's break this down into two parts:

Part 1

const body = await request.body();
if (!request.hasBody) {
  response.status = 400;
  response.body = {
    success: false,
    message: "No data provided",
  };
  return;
}

All we are doing here is checking if the user is sending data in body. If not, then we return a status 400 and in the body return success: false and message: .

Part 2

try {
  await TodoModel.add(
    { todo: body.value.todo, isCompleted: false },
  );
  response.body = {
    success: true,
    message: "The record was added successfully",
  };
} catch (error) {
  response.status = 400;
  response.body = {
    success: false,
    message: `Error: ${error}`,
  };
}

If there is no error, the TodoModel.add() function is called and simply returns a status of 200 and a confirmation message to the user.

Otherwise it just throws a similar error that we did in the previous API.

Now we're done. Fire up your terminal and make sure your MySQL instance is running. In your terminal type:

$ deno run --allow-net server.ts

Go to Postman and run the API route for this controller:

running [POST] localhost:8080/todos => Will add a new new todo item

running [POST] localhost:8080/todos => Will return all todos, notice how the new added item is being returned as well

This is great, now we have two working APIs. Only three more to go.

[GET] todo by id API

In your models/todo.ts file, add definition for these two functions, doesExistById() and getById():

export default {
   /**
   * Takes in the id params & checks if the todo item exists
   * in the database
   * @param id
   * @returns boolean to tell if an entry of todo exits in table
   */
  doesExistById: async ({ id }: Todo) => {
    const [result] = await client.query(
      `SELECT COUNT(*) count FROM ${TABLE.TODO} WHERE id = ? LIMIT 1`,
      [id],
    );
    return result.count > 0;
  },
  /**
   * Takes in the id params & returns the todo item found
   * against it.
   * @param id
   * @returns object of todo item
   */
  getById: async ({ id }: Todo) => {
    return await client.query(
      `SELECT * FROM ${TABLE.TODO} WHERE id = ?`,
      [id],
    );
  },
}

Let's talk about each function one by one:

doesExistById takes in an id and returns a boolean indicating whether a particular todo exists in the database or not.

Let's break this function down:

const [result] = await client.query(
  `SELECT COUNT(*) count FROM ${TABLE.TODO} WHERE id = ? LIMIT 1`,
  [id],
);
return result.count > 0;

We simply check the count here in the table against a particular todo id. If the count is greater than zero, we return true. Otherwise, we return false.

getById returns the todo item against a particular id:

return await client.query(
  `SELECT * FROM ${TABLE.TODO} WHERE id = ?`,
  [id],
);

We are simply running a MySQL query here to get a todo by id and returning the result as-is.

Next, go to your controllers/todo.ts file and add a definition for a getTodoById controller method:

export default {
   /**
   * @description Get todo by id
   * @route GET todos/:id
   */
  getTodoById: async (
    { params, response }: { params: { id: string }; response: any },
  ) => {
    try {
      const isAvailable = await TodoModel.doesExistById(
        { id: Number(params.id) },
      );

      if (!isAvailable) {
        response.status = 404;
        response.body = {
          success: false,
          message: "No todo found",
        };
        return;
      }

      const todo = await TodoModel.getById({ id: Number(params.id) });
      response.status = 200;
      response.body = {
        success: true,
        data: todo,
      };
    } catch (error) {
      response.status = 400;
      response.body = {
        success: false,
        message: `Error: ${error}`,
      };
    }
  },
}

Let's break this down into two smaller parts:

const isAvailable = await TodoModel.doesExistById(
  { id: Number(params.id) },
);

if (!isAvailable) {
  response.status = 404;
  response.body = {
    success: false,
    message: "No todo found",
  };
  return;
}

First we check if the todo exists in the database against an id by using this method:

const isAvailable = await TodoModel.doesExistById(
  { id: Number(params.id) },
);

Here we need to convert params.id into a Number because our todo interface only accepts id as a number. Next, we just pass params.id to the doesExistById method. This method will return as a boolean.

Then we simply check if the todo is not available and return a 404 method with our standard response like with the previous endpoints:

if (!isAvailable) {
  response.status = 404;
  response.body = {
    success: false,
    message: "No todo found",
  };
  return;
}

Then we have:

try {
const todo: Todo = await TodoModel.getById({ id: Number(params.id) });
response.status = 200;
response.body = {
  success: true,
  data: todo,
};
} catch (error) {
response.status = 400;
response.body = {
  success: false,
  message: `Error: ${error}`,
};

This is similar to what we were doing in our previous APIs. Here we are simply getting data from the db, setting the variable todo, and then returning the response. If there is an error we simply return a standard error message in the catch block back to the user.

Now fire up your terminal and make sure your MySQL instance is running. In your terminal type:

$ deno run --allow-net server.ts

Go to Postman and run the API route for this controller.

Remember that every time we restart our server we reset the db. If you don't want this behavior, you can simply comment out the run function in the file db/client.ts.

running [POST] localhost:8080/todos => Will add a new new todo item

running [POST] localhost:8080/todos => Will return all todos

running [GET] localhost:8080/todos/:id => will return the todo for that id if found

will return the todo for that id if found" width="600" height="400" loading="lazy"> running [GET] localhost:8080/todos/ => returns status 404 with not found error message

So far we have done APIs for:

Get all todos
Create a new todo
Get a todo by ID

And here are the remaining APIs:

Update a todo by ID
Delete a todo by ID

[PUT] update todo by id API

Let's create a model for this API first. Go in our models/todo.ts file and add a definition for an updateById function:

**
 * Updates the content of a single todo item
 * @param id
 * @param todo
 * @param isCompleted
 * @returns integer (count of effect rows)
 */
updateById: async ({ id, todo, isCompleted }: Todo) => {
  const result = await client.query(
    `UPDATE ${TABLE.TODO} SET todo=?, isCompleted=? WHERE id=?`,
    [
      todo,
      isCompleted,
      id,
    ],
  );
  // return count of rows updated
  return result.affectedRows;
},

The updateById takes in 3 params: id, todo, and isCompleted.

We simply run a MySQL query inside this function:

onst result = await client.query(
  `UPDATE ${TABLE.TODO} SET todo=?, isCompleted=? WHERE id=?`,
  [
    todo,
    isCompleted,
    id,
  ],
);

This updates a single todo item's todo and isCompleted by a specific id.

Next we return a count of rows updated by this query by doing:

  // return count of rows updated
  return result.affectedRows;

The count will either be 0 or 1, but never more than 1. This is because we have unique IDs in our database – multiple todos with the same ID cannot exist.

Next go to our controllers/todo.ts file and add a definition for a updateTodoById function:

updateTodoById: async (
  { params, request, response }: {
    params: { id: string };
    request: any;
    response: any;
  },
) => {
  try {
    const isAvailable = await TodoModel.doesExistById(
      { id: Number(params.id) },
    );
    if (!isAvailable) {
      response.status = 404;
      response.body = {
        success: false,
        message: "No todo found",
      };
      return;
    }

    // if todo found then update todo
    const body = await request.body();
    const updatedRows = await TodoModel.updateById({
      id: Number(params.id),
      ...body.value,
    });
    response.status = 200;
    response.body = {
      success: true,
      message: `Successfully updated ${updatedRows} row(s)`,
    };
  } catch (error) {
    response.status = 400;
    response.body = {
      success: false,
      message: `Error: ${error}`,
    };
  }
},

This is almost the same as of our previous APIs we wrote. The part that's new here is this:

// if todo found then update todo
const body = await request.body();
const updatedRows = await TodoModel.updateById({
  id: Number(params.id),
  ...body.value,
});

We simple get the body that the user sends us in JSON and pass the body to our TodoModel.updateById function.

We have to convert the id to a number to comply with our Todo interface.

The query is executed and returns the count of updated rows. From there we simply return it in our response. If there is an error it goes to the catch block where we return our standard response message.

Let's run this and see if it works. Make sure your MySQL instance is running and run the following from your terminal:

$ deno run --allow-net server.ts

Go to Postman and run the API route for this controller:

running [PUT] localhost:8080/todos/:id => will update content of that todo by given id

running [GET] localhost:8080/todos/ => will return all todos, see how the todo you updated is also showing there.

[DELETE] todo by id API

In your models/todo.ts file create a function called deleteById:

/**
 * Deletes a todo by ID
 * @param id
 * @returns integer (count of effect rows)
 */
deleteById: async ({ id }: Todo) => {
  const result = await client.query(
    `DELETE FROM ${TABLE.TODO} WHERE id = ?`,
    [id],
  );
  // return count of rows updated
  return result.affectedRows;
},

Here we simply pass an id as a param and then use the delete MySQL query. We then return the updated count of rows. The updated count will either be 0 or 1 because the ID of each todo is unique.

Next, go in your controllers/todo.ts file and define a deleteByTodoId method:

/**
 * @description Delete todo by id
 * @route DELETE todos/:id
 */
deleteTodoById: async (
  { params, response }: { params: { id: string }; response: any },
) => {
  try {
    const updatedRows = await TodoModel.deleteById({
      id: Number(params.id),
    });
    response.status = 200;
    response.body = {
      success: true,
      message: `Successfully updated ${updatedRows} row(s)`,
    };
  } catch (error) {
    response.status = 400;
    response.body = {
      success: false,
      message: `Error: ${error}`,
    };
  }
},

This is pretty straightforward. We pass the params.id to our TodoModel.deleteById method and return the count of rows updated with this query.

If anything goes wrong an error is thrown in the catch block which returns our standard error response.

Let's check this out.

Make sure your MySQL instance is running. In your terminal type:

$ deno run --allow-net server.ts

Go to Postman and run the API route for this controller:

running [GET] localhost:8080/todos/ => will return all todos

running [DELETE] localhost:8080/todos/:id => will delete a todo by ID

running [GET] localhost:8080/todos/ => will return all todos, see how todo with "id" is no longer here

With this we are done with our Deno + Oak + MySQL tutorial.

The entire source code is available here: https://github.com/adeelibr/deno-playground. If you find an issue, just let me know. Or feel free to make a pull request and I'll give you credit in the repository.

If you found this tutorial helpful, please share it. And as always, I am available on Twitter under @adeelibr. I would love to hear your thoughts on it.

How to Create a Todo API in Deno and Oak

freeCodeCamp — Fri, 29 May 2020 11:33:00 +0000

By Adeel Imran

I am a JavaScript/Node developer who secretly likes (actually, loves and adores) Deno. I have been a huge fan of Deno ever since it was announced and I've been wanting to play with it.

This tutorial focuses on creating a set of REST APIs for a Todo application. Keep in mind that I did not touch on the database here – I will cover that in another article.

At any point if you feel lost or want to check a reference, here is the entire source code of this tutorial: Chapter 1: Oak.

_Photo by [Unsplash](https://unsplash.com/@bernardtheclerk?utm_source=ghost&utm_medium=referral&utm_campaign=api-credit">Bernard de Clerk / Things we will cover

Create a basic server

Create 5 APIs (routes/controller)

Create a middleware to log API requests as they are made in the console

Create a not found (404) middleware when the user tries to access an unknown API

What will we need

An installed version of Deno (don't worry I'll walk you through it)
A tiny bit of knowledge of Typescript
Would be awesome if you have worked with Node/Express before (don't worry if you haven't — this tutorial is very basic)

Let's get started

First things first let's install Deno. I am on a Mac computer so I am using brew. Simply open your terminal and type:

$ brew install deno

But if you are using a different operating system, just head over to deno.land installation. They have a lot of ways you can easily install it on your machine.

Once you have it installed, close the terminal, open a new one, and type:

$ deno --version

It should output something like this:

running command "deno --version" to see which version of deno is installed

Awesome! With this we are almost done with 10% of this tutorial.

Let's move ahead and create the backend API for our Todo app.

Setting up the project

Before you move on, here is the entire source code of this tutorial: Chapter 1: Oak.

Let's get started:

Create a new folder and call it chapter_1:oak (but you can call it anything you want)
Once you create a folder simply cd into your new project. Create a file called server.ts and write the following code in it:

import { Application } from "https://deno.land/x/oak/mod.ts";

const app = new Application();
const port: number = 8080;

console.log('running on port ', port);
await app.listen({ port });

Let's run this file. Open your terminal and in your project root folder type:

$ deno run --allow-net server.ts

I will talk about what the --allow-net flag does, but for now just bear with me ?.

You should get something like this:

What we have done so far is create a server which listens on port 8080. It doesn't do much right now besides being able to run on port 8080.

If you have used JavaScript before, one thing you might have noticed is we are importing packages in a different way. We have to do something like:

import { Application } from "https://deno.land/x/oak/mod.ts";

When you run deno run ---allow-net in your terminal, Deno will look at all your imports and install them locally in your machine if they are not there.

The first time you run this it will go to this URL https://deno.land/x/oak/mod.ts and install the oak package. Oak is basically a Deno framework for writing API's. It will put it somewhere locally in your cache.

In the next line we do this:

const app = new Application();

This creates a new instance of our application, and it will be the basis of everything as you progress further in this tutorial. You can add routes to the application instance, attach middleware like API logging, write a 404 not found, and so on.

Then we write:

const port: number = 8080;
// const port = 8080; // => can also be written like this

Both are the same and do the same thing. The only difference is writing const port: number = 8080 tells Typescript that port variable is of type number.

If you were to write const port: number = "8080", this would throw an error in your terminal, as port is of type number. But we are trying to assign it a string of value "8080".

If you want to learn more about different types of types (pun intended) check out this very easy and basic guide on Basic types by Typescript. Just give it a quick glance for 2-3 minutes and head back here.

And in the end we have:

console.log('running on port ', port);
await app.listen({ port });

We simply console here the port number and tell Deno to listen to the port, which is 8080.

It isn't doing much right now. Let's make it do something basic like show a JSON message in your browser when you go to http:localhost:8080.

Add the following to your server.ts file:

import { Application, Router } from "https://deno.land/x/oak/mod.ts";

const app = new Application();
const port: number = 8080;

const router = new Router();
router.get("/", ({ response }: { response: any }) => {
  response.body = {
    message: "hello world",
  };
});
app.use(router.routes());
app.use(router.allowedMethods());

console.log('running on port ', port);
await app.listen({ port });

The new thing added here is that we are now also importing Router along with Application from oak in line 1.

Next what we do is:

const router = new Router();
router.get("/", ({ response }: { response: any }) => {
  response.body = {
    message: "hello world",
  };
});
app.use(router.routes());
app.use(router.allowedMethods());

We create a new router instance by doing const router = new Router() and then we create a new route called / which is of type get.

Let's break this down:

router.get("/", ({ response }: { response: any }) => {
  response.body = {
    message: "hello world",
  };
});

router.get takes 2 parameters. The first is route which we have set to / and the second is function. The function itself takes an argument which is an object. What I am doing here is destructuring the object and getting only response.

Next I am type checking response similar to how I did const port: number = 8080;. All I am doing is { response }: { response: any } which is telling TypeScript here that the response which I have destructed can be of type any.

any helps you avoid type checking in TypeScript. You can read more about it here.

Then all I am doing is taking that response object and setting response.body.message = "hello world";.

response.body = {
  message: "hello world",
};

Last but not least, we just add these two lines:

app.use(router.routes());
app.use(router.allowedMethods());

This tells Deno to include all routes by our router (currently we only have one) and the next line tells Deno to allow all methods for this route(s) like GET, POST, PUT, DELETE.

And now we are done. ✅ Let's run this and see what we have:

$ deno run --allow-net server.ts

The ---allow-net property tells Deno that this app gives the user the permission to access its content via the port opened up.

Now open your favorite browser and go to http://localhost:8080. You will see something like this:

Result of running localhost:8080 on your browser

Honestly the hardest part is done. Conceptually we are 60% there.

Master Yoda approves

Awesome.

Just one last thing before we start with our Todo API. Let's replace:

console.log('running on port ', port);
await app.listen({ port });

with:

app.addEventListener("listen", ({ secure, hostname, port }) => {
  const protocol = secure ? "https://" : "http://";
  const url = `${protocol}${hostname ?? "localhost"}:${port}`;
  console.log(`Listening on: ${port}`);
});

await app.listen({ port });

The code we had before was not very accurate, because we were simply console logging a message and then waiting for the app to start listening on a port.

With the later version we wait for the app to start listening on port and we can listen by adding an event listener to our app instance with the following: app_.addEventListener_("listen", ({ secure, hostname, port }) => {}.

The first param is the event we want to listen for (which is listen ?) and then the second param is an object which we destruct to { secure, hostname, port }. Secure is a boolean, hostname is a string, and port is a number.

Now when we start our app, it will only console the message once the app actually starts listening on port.

We can just go one step ahead and make it more colorful. Let's add a new module to the top of the file in server.ts:

import { green, yellow } from "https://deno.land/std@0.53.0/fmt/colors.ts";

And then inside our event listener method we can replace:

console.log(`Listening on: ${port}`);

with:

console.log(`${yellow("Listening on:")} ${green(url)}`);

Now when we do:

$ deno run --allow-net server.ts

it will show this in our console:

Cool, now we have a colourful console.

If you get stuck anywhere you can simply go to the source code of this tutorial here.

Let's create our Todo API's routes next.

Create a new folder in your root folder called routes and inside that folder create a file called todo.ts
At the same time in your root folder create a new folder called controllers and inside that folder create a file called todo.ts

Let's first touch the controllers/todo.ts file:

export default {
  getAllTodos: () => {},
  createTodo: async () => {},
  getTodoById: () => {},
  updateTodoById: async () => {},
  deleteTodoById: () => {},
};

We are simply exporting an object here with some named functions which are empty (for now).

Next go inside your file routes/todo.ts and type this:

import { Router } from "https://deno.land/x/oak/mod.ts";

const router = new Router();
// controller
import todoController from "../controllers/todo.ts";

router
  .get("/todos", todoController.getAllTodos)
  .post("/todos", todoController.createTodo)
  .get("/todos/:id", todoController.getTodoById)
  .put("/todos/:id", todoController.updateTodoById)
  .delete("/todos/:id", todoController.deleteTodoById);

export default router;

This might look familiar to people who have worked with Node and Express.

All we are doing here is importing Route from oak and then setting up a new instance of Router by doing const router = new Router();.

Next we import our controllers by doing:

import todoController from "../controllers/todo.ts";

One thing to notice here in Deno is every time we import a local file in our Deno project we have to provide the file extension. This is because Deno doesn't know whether the file being imported is a .js or .ts file.

Moving forward we simply set all of our routes according to REST conventions:

router
  .get("/todos", todoController.getAllTodos)
  .post("/todos", todoController.createTodo)
  .get("/todos/:id", todoController.getTodoById)
  .put("/todos/:id", todoController.updateTodoById)
  .delete("/todos/:id", todoController.deleteTodoById);

The code above will translate to our API definition like this:

TYPE	API ROUTE
GET	/todos
GET	/todos/:id
POST	/todos
PUT	/todos/:id
DELETE	/todos/:id

and at the end we simply export our router by doing _export_ _default_ router;.

We are done with creating our routes structure. (Now, each route doesn't do anything because our controllers are empty, we will add functionality to them in a bit.)

Here's the last piece of the puzzle before we start adding functionality to each route controller. We need to attach this router to our app instance.

So head over to server.ts file and do the following:

Add this to the very top:

// routes
import todoRouter from "./routes/todo.ts";

Remove this piece of code:

const router = new Router();
router.get("/", ({ response }: { response: any }) => {
  response.body = {
    message: "hello world",
  };
});
app.use(router.routes());
app.use(router.allowedMethods());

Replace it with:

app.use(todoRouter.routes());
app.use(todoRouter.allowedMethods());

This is it – we are done. Your server.ts file should look like this now:

import { Application } from "https://deno.land/x/oak/mod.ts";
import { green, yellow } from "https://deno.land/std@0.53.0/fmt/colors.ts";

// routes
import todoRouter from "./routes/todo.ts";

const app = new Application();
const port: number = 8080;

app.use(todoRouter.routes());
app.use(todoRouter.allowedMethods());

app.addEventListener("listen", ({ secure, hostname, port }) => {
  const protocol = secure ? "https://" : "http://";
  const url = `${protocol}${hostname ?? "localhost"}:${port}`;
  console.log(
    `${yellow("Listening on:")} ${green(url)}`,
  );
});

await app.listen({ port });

If you got stuck anywhere while following this, simple head over to the source code of this tutorial here.

Awesome, now we have our routes with no functionality at the moment. So let's add that functionality in our controllers.

But before we do that we have to create 2 more (tiny) files.

In your root folder create a new folder called interfaces and inside that folder create a file called Todo.ts (make sure Todo is capitalized, as it won't give any syntax error here if you don't – these are just conventions.)
Also in your root folder create a new folder called stubs and inside that folder create a file called todos.ts

Let's create an interface in our interfaces/Todo.ts file. Simply add the following code:

export default interface Todo {
  id: string,
  todo: string,
  isCompleted: boolean,
}

What is an interface?

One of the core things in TypeScript is checking the shape that value has. Similar to const port: number = 8080 or { response }: { response : any }, we can also type check an object.

In TypeScript, interfaces fill the role of naming these types, and are a powerful way of defining contracts within your code as well as contracts with code outside of your project.

Here is an another example of an interface:

// We have an interface
interface LabeledValue {
  label: string;
}

// the arg passed to this function labeledObj is 
// of type LabeledValue (interface)
function printLabel(labeledObj: LabeledValue) {
  console.log(labeledObj.label);
}

let myObj = {label: "Size 10 Object"};
printLabel(myObj);

Hopefully this example gives you a bit more insight into interfaces. If you want more detailed information check out the docs on interfaces here.

Now that our interface is ready, let's mock some data (since we don't have an actual database for this tutorial).

Let's create a mock list of todos first in our stubs/todos.ts file. Simply add the following:

import { v4 } from "https://deno.land/std/uuid/mod.ts";
// interface
import Todo from '../interfaces/Todo.ts';

let todos: Todo[] = [
  {
    id: v4.generate(),
    todo: 'walk dog',
    isCompleted: true,
  },
  {
    id: v4.generate(),
    todo: 'eat food',
    isCompleted: false,
  },
];

export default todos;

Two things to notice here: we add a new package and use its method v4 by doing _import_ { v4 } _from_ "https://deno.land/std/uuid/mod.ts";. Then every time we use v4.generate() it will create a new random string of id.

The id can not be a number, only a string because in our Todo interface we have defined id as a string.

The other thing to focus on here is let _todos_: _Todo_[] = []. This basically tells Deno that our todos array is of type Todo (which is awesome, our compiler now automagically knows that each item in our array can only have {**id**: _string_, **todo**: _string_ & **isCompleted**: _boolean_} it will not accept any other key).

If you want to learn more about interfaces in TypeScript check out this amazing detailed documentation on interfaces here.

Awesome. If you have come this far, give yourself a pat on the back. Good job everyone.

The Rock appreciates all the effort you are doing

Let's work on our controllers

In your file controllers/todo.ts:

export default {
  getAllTodos: () => {},
  createTodo: async () => {},
  getTodoById: () => {},
  updateTodoById: async () => {},
  deleteTodoById: () => {},
};

Let's write the controller for getAllTodos:

// stubs
import todos from "../stubs/todos.ts";

export default {
  /**
   * @description Get all todos
   * @route GET /todos
   */
  getAllTodos: ({ response }: { response: any }) => {
    response.status = 200;
    response.body = {
      success: true,
      data: todos,
    };
  },
  createTodo: async () => {},
  getTodoById: () => {},
  updateTodoById: async () => {},
  deleteTodoById: () => {},
};

Before I begin on this block of code, let me explain that every controller has an argument – let's call it context.

So we can deconstruct _getAllTodos_: (context) => {} to:

getAllTodos: ({ request, response, params }) => {}

And since we are using typescript we have to add type checking to all of these variables:

getAllTodos: (
  { request, response, params }: { 
    request: any, 
    response: any, 
    params: { id: string },
  },
) => {}

So we have added type checks to all 3 { request, response, params }

request is what the user sends us (information like headers and JSON data)
response is what we send the user back in the API response
params is what we define in our router routes, that is:

.get("/todos/:id", ({ params}: { params: { id: string } }) => {})

So the :id in /todos/:id is the param. Params are a way to get information from the URL. In this example we know that we have an /:id . So when the user tries to access this API (that is, /todos/756) 756 is basically the :id param. Since it is in the URL we know it is of type string.

Now that we have our basic definitions defined let's get back to our todos controller:

// stubs
import todos from "../stubs/todos.ts";

export default {
  /**
   * @description Get all todos
   * @route GET /todos
   */
  getAllTodos: ({ response }: { response: any }) => {
    response.status = 200;
    response.body = {
      success: true,
      data: todos,
    };
  },
  createTodo: async () => {},
  getTodoById: () => {},
  updateTodoById: async () => {},
  deleteTodoById: () => {},
};

For getAllTodos we only need response . If you remember, response is what is needed to send data back to the user.

For people coming from a Node and Express background, one big thing that is different here is that we don't need to return the response object. Deno does this for us automatically.

All we have to do is set response.status which in this case is 200.

Creating a route middleware for routes that aren't found

In your root folder create a new folder called middlewares. Inside that folder create a file called notFound.ts and inside this file add this code:

export default ({ response }: { response: any }) => {
  response.status = 404;
  response.body = {
    success: false,
    message: "404 - Not found.",
  };
};

Here we aren't doing anything new – it is very similar to our controllers structure. Just returning a status 404 (which means not found) along with a JSON object for { success, message }.

Next go in your server.ts file and add the following content:

Add this import somewhere at the top:

// not found
import notFound from './middlewares/notFound.ts';

And then just below your app.use(todoRouter.allowedMethods()) add this line like this:

app.use(todoRouter.routes());
app.use(todoRouter.allowedMethods());

// 404 page
app.use(notFound);

The order of execution is important here: every time we try to access an API end point it will first match/check routes from our todoRouter. If none are found, it will then execute app_.use_(notFound);.

Let's see if this works.

Restart the server:

$ deno run --allow-net server.ts

Open up a new tab in Postman. Set the request to GET and in the URL bar type http://localhost:8080/something-unknown, then hit Send.

So we now have a route middleware that we put at the end of our routes in server.ts as app_.use_(notFound);. If no route matches this middleware it will execute and return a 404 status code (which means not found). Then we simply send a response message like always which is {success, message}.

Pro tip: We have decided that {success, message} is what we return in failed scenarios and {success, data} is what we return to user in success scenarios. So we can even make these to object/shapes as interfaces and add them to our project to ensure consistency and safe type checking.

Cool, now we are done with one of our middlewares – let's add the other middleware for logging our APIs in the console.

Reminder: If you get stuck anywhere you can use the source code here.

Logging APIs in console

In your middlewares folder create a new file called logger.ts and enter the following code:

import {
  green,
  cyan,
  white,
  bgRed,
} from "https://deno.land/std@0.53.0/fmt/colors.ts";

const X_RESPONSE_TIME: string = "X-Response-Time";

export default {
  logger: async (
    { response, request }: { response: any, request: any },
    next: Function,
  ) => {
    await next();
    const responseTime = response.headers.get(X_RESPONSE_TIME);
    console.log(`${green(request.method)} ${cyan(request.url.pathname)}`);
    console.log(`${bgRed(white(String(responseTime)))}`);
  },
  responseTime: async (
    { response }: { response: any },
    next: Function,
  ) => {
    const start = Date.now();
    await next();
    const ms: number = Date.now() - start;
    response.headers.set(X_RESPONSE_TIME, `${ms}ms`)
  },
};

In your server.ts file add this code:

Import this somewhere at the top:

// logger
import logger from './middlewares/logger.ts';

Just above your todoRouter code add these middlewares like this:

// order of execution is important;
app.use(logger.logger);
app.use(logger.responseTime);

app.use(todoRouter.routes());
app.use(todoRouter.allowedMethods());

Now let's discuss what we just did.

Let's talk about the logger.ts file and break it down into bits:

import {
  green,
  cyan,
  white,
  bgRed,
} from "https://deno.land/std@0.53.0/fmt/colors.ts";

I am importing some console colors and console background colors that I want to use in API logging.

This is similar to what we did in our eventListener in our server.ts file. We will use colors in our console to log API requests.

Next I set const X_RESPONSE_TIME: string = "X-Response-Time";. This is the header we will inject in our API requests as they come into our server. I am calling this X_RESPONSE_TIME and its value is X-Response-Time. I will demonstrate its usage in a bit.

Next we simply export an object like this:

export default {
    logger: async ({ response, request }, next) {}
    responseTime: async ({ response }, next) {}
};

And then we simply use it inside our server.ts file like this:

// order of execution is important;
app.use(logger.logger);
app.use(logger.responseTime);

Let's now discuss what is happening in our logger middleware code and discuss it execution style using next():

Execution of order of logging middleware when GET /todos API is called.

The only difference here and in the controllers we had before is the use of the next() function. This functions helps us jump from one controller to the other as shown in the image below.

So in:

export default {
  logger: async (
    { response, request }: { response: any, request: any },
    next: Function,
  ) => {
    await next();
    const responseTime = response.headers.get(X_RESPONSE_TIME);
    console.log(`${green(request.method)} ${cyan(request.url.pathname)}`);
    console.log(`${bgRed(white(String(responseTime)))}`);
  },
  responseTime: async (
    { response }: { response: any },
    next: Function,
  ) => {
    const start = Date.now();
    await next();
    const ms: number = Date.now() - start;
    response.headers.set(X_RESPONSE_TIME, `${ms}ms`)
  },
};

Keep in mind that this is what we have in our server.ts file:

// order of execution is important;
app.use(logger.logger);
app.use(logger.responseTime);

app.use(todoRouter.routes());
app.use(todoRouter.allowedMethods());

The order of execution is as follows:

logger.logger middleware
logger.responseTime middleware
todoRouter controller (whatever path is called by the user, for the purpose of explanation I am assuming that the user called GET /todos API to get all todos.)

So it will first execute logger.logger middleware which is this:

logger: async (
    { response, request }: { response: any, request: any },
    next: Function,
  ) => {
    await next();
    const responseTime = response.headers.get(X_RESPONSE_TIME);
    console.log(`${green(request.method)} ${cyan(request.url.pathname)}`);
    console.log(`${bgRed(white(String(responseTime)))}`);
  },

It will come inside this function and immediately as it reads await next() it quickly jumps to the next middleware which is responseTime:

Sharing the image above again for revision.

Inside responseTime, it only executes two lines which are (look at execution order 2 in image above):

const start = Date.now();
await next();

before jumping to the getAllTodos controller. Once it goes inside getAllTodos it will run the entire code inside that controller.

Since in that controller we are not using next() it will simply return the flow of logic back to responseTime controller. There it will run the following:

const ms: number = Date.now() - start;
response.headers.set(X_RESPONSE_TIME, `${ms}ms`)

Now keeping in perspective of the order of execution which is 2, 3, 4 (look at the image above).

This is what happens:

We capture the data in ms by doing const start = Date.now();. Then we immediately call next() which goes to getAllTodos controller and runs the entire code. Then it comes back in the responseTime controller.
We then subtract that start date with whatever the date is at that moment by doing const _ms_: _number_ = _Date.now_() - start; ms. Here it will return a number which is basically the difference in milliseconds that will tell us all the time it took Deno to execute our getAllTodos controller.

Sharing the image once again for review:

Next we simply set headers in our response like this:

response.headers.set(X_RESPONSE_TIME, `${ms}ms`)

Which just sets the header value X-Response-Time to the milliseconds it took Deno to execute our API.

Then from execution order 4 we move back to execution order 5 (have a look at the image above for reference).

Here we simply do:

const responseTime = response.headers.get(X_RESPONSE_TIME);
console.log(`${green(request.method)} ${cyan(request.url.pathname)}`);
console.log(`${bgRed(white(String(responseTime)))}`);

We get the time we passed in the X-Response-Time
Then we take that time and simply console it colourfully in the console.

request.method tells us the method used to call our API, that is GET, PUT etc while request.url.pathname will tell the API which path the user used i.e, /todos

Let's see if this works.

Restart the server:

$ deno run --allow-net server.ts

Open up a new tab in Postman. Set the request to GET, type in http://localhost:8080/todos, and hit Send.

Hit the API a couple of times in Postman. Then when you go back to the console, you should see something like this:

API being logged in our console

This is it – we are done.

If you still feel stuck, take a look at the entire source code for this tutorial here: github.com/adeelibr/deno-playground/tree/master/chapter_1:oak

I hope that you found this article useful and that it was able to help you learn something today.

If you liked it, please do share it on social media. If you want to have a discussion about it, reach out to me on Twitter.

The Deno Handbook – A TypeScript Runtime Tutorial with Code Examples

Flavio Copes — Tue, 12 May 2020 12:00:00 +0000

I explore new projects every week, and it’s rare that one grabs my attention as much as Deno did.

In this post I want to get you up to speed with Deno quickly. We'll compare it with Node.js, and build your first REST API with it.

What is Deno?
Why Deno? Why now?
Should you learn Deno?
Will it replace Node.js?
First-class TypeScript support
Similarities and differences with Node.js
No package manager
Install Deno
The Deno commands
Your first Deno app
Deno code examples
Your first Deno app (for real)
The Deno sandbox
Formatting code
The standard library
Another Deno example
Is there an Express/Hapi/Koa/* for Deno?
Example: use Oak to build a REST API
Find out more
A few more random tidbits

And note: You can get a PDF/ePub/Mobi version of this Deno Handbook here.

What is Deno?

If you are familiar with Node.js, the popular server-side JavaScript ecosystem, then Deno is just like Node. Except deeply improved in many ways.

Let’s start from a quick list of the features I like the most about Deno:

It is based on modern features of the JavaScript language
It has an extensive standard library
It has TypeScript at its core, which brings a huge advantage in many different ways, including a first-class TypeScript support (you don’t have to separately compile TypeScript, it’s automatically done by Deno)
It embraces ES modules
It has no package manager
It has a first-class await
It has a built-in testing facility
It aims to be browser-compatible as much as it can, for example by providing a built-in fetch and the global window object

We’ll explore all of those features in this guide.

After you use Deno and learn to appreciate its features, Node.js will look like something old.

Especially because the Node.js API is callback-based, as it was written way before promises and async/await. There’s no change available for that in Node, because such a change would be monumental. So we’re stuck with callbacks or with promisifying API calls.

Node.js is awesome and will continue to be the de facto standard in the JavaScript world. But I think we’ll gradually see Deno get adopted more and more because of its first-class TypeScript support and modern standard library.

Deno can afford to have everything written with modern technologies, since there’s no backward compatibility to maintain. Of course there’s no guarantee that in a decade the same will happen to Deno and a new technology will emerge, but this is the reality at the moment.

Why Deno? Why now?

Deno was announced almost 2 years ago by the original creator of Node.js, Ryan Dahl, at JSConf EU. Watch the YouTube video of the talk, it’s very interesting and it’s a mandatory watch if you are involved in Node.js and JavaScript in general.

Every project manager must make decisions. Ryan regretted some early decisions in Node. Also, technology evolves, and today JavaScript is a totally different language than what it was back in 2009 when Node started. Think about the modern ES6/2016/2017 features, and so on.

So he started a new project to create some sort of second wave of JavaScript-powered server side apps.

The reason I am writing this guide now and not back then is because technologies need a lot of time to mature. And we have finally reached Deno 1.0 (1.0 should be released on May 13, 2020), the first release of Deno officially declared stable.

That’s might seem to be just a number, but 1.0 means there will not be major breaking changes until Deno 2.0. This is a big deal when you dive into a new technology - you don’t want to learn something and then have it change too fast.

Should you learn Deno?

That’s a big question.

Learning something new such as Deno is a big effort. My suggestion is that if you are starting out now with server-side JS and you don’t know Node yet, and have never written any TypeScript, I’d start with Node.

No one was ever fired for choosing Node.js (paraphrasing a common quote).

But if you love TypeScript, don’t depend on a gazillion npm packages in your projects and you want to use await anywhere, hey Deno might be what you’re looking for.

Will it replace Node.js?

No. Node.js is a giant, well established, incredibly well-supported technology that is going to stay around for decades.

First-class TypeScript support

Deno is written in Rust and TypeScript, two of the languages that are really growing fast today.

In particular, being written in TypeScript means we get a lot of the benefits of TypeScript even if we might choose to write our code in plain JavaScript.

And running TypeScript code with Deno does not require a compilation step - Deno does that automatically for you.

You are not forced to write in TypeScript, but the fact the core of Deno is written in TypeScript is huge.

First, an increasingly large percentage of JavaScript programmers love TypeScript.

Second, the tools you use can infer many information about software written in TypeScript, like Deno.

This means that when we code in VS Code, for example (which of course has a tight integration with TypeScript since both are developed at MicroSoft), we can get benefits like type checking as we write our code, and advanced IntelliSense features. In other words the editor can help us in a deeply useful way.

Similarities and differences with Node.js

Since Deno is basically a Node.js replacement, it’s useful to compare the two directly.

Similarities:

Both are developed upon the V8 Chromium Engine
Both are great for developing server-side with JavaScript

Differences:

Node is written in C++ and JavaScript. Deno is written in Rust and TypeScript.
Node has an official package manager called npm. Deno does not, and instead lets you import any ES Module from URLs.
Node uses the CommonJS syntax for importing pacakges. Deno uses ES Modules, the official way.
Deno uses modern ECMAScript features in all its API and standard library, while Node.js uses a callbacks-based standard library and has no plans to upgrade it.
Deno offers a sandbox security layer through permissions. A program can only access the permissions set to the executable as flags by the user. A Node.js program can access anything the user can access.
Deno has for a long time envisioned the possibility of compiling a program into an executable that you can run without external dependencies, like Go, but it’s still not a thing yet. That’d be a game changer.

No package manager

Having no package manager and having to rely on URLs to host and import packages has pros and cons. I really like the pros: it’s very flexible, and we can create packages without publishing them on a repository like npm.

I think that some sort of package manager will emerge, but nothing official is out yet.

The Deno website provides code hosting (and thus distribution through URLs) to 3rd party packages: https://deno.land/x/

Install Deno

Enough talk! Let’s install Deno.

The easiest way is to use Homebrew:

brew install deno

Once this is done, you will have access to the deno command. Here’s the help that you can get using deno --help:

flavio@mbp~> deno --help
deno 0.42.0
A secure JavaScript and TypeScript runtime

Docs: https://deno.land/std/manual.md
Modules: https://deno.land/std/ https://deno.land/x/
Bugs: https://github.com/denoland/deno/issues

To start the REPL, supply no arguments:
  deno

To execute a script:
  deno run https://deno.land/std/examples/welcome.ts
  deno https://deno.land/std/examples/welcome.ts

To evaluate code in the shell:
  deno eval "console.log(30933 + 404)"

Run 'deno help run' for 'run'-specific flags.

USAGE:
    deno [OPTIONS] [SUBCOMMAND]

OPTIONS:
    -h, --help
            Prints help information

    -L, --log-level 
            Set log level [possible values: debug, info]

    -q, --quiet
            Suppress diagnostic output
            By default, subcommands print human-readable diagnostic messages to stderr.
            If the flag is set, restrict these messages to errors.
    -V, --version
            Prints version information


SUBCOMMANDS:
    bundle         Bundle module and dependencies into single file
    cache          Cache the dependencies
    completions    Generate shell completions
    doc            Show documentation for a module
    eval           Eval script
    fmt            Format source files
    help           Prints this message or the help of the given subcommand(s)
    info           Show info about cache or info related to source file
    install        Install script as an executable
    repl           Read Eval Print Loop
    run            Run a program given a filename or url to the module
    test           Run tests
    types          Print runtime TypeScript declarations
    upgrade        Upgrade deno executable to newest version

ENVIRONMENT VARIABLES:
    DENO_DIR             Set deno's base directory (defaults to $HOME/.deno)
    DENO_INSTALL_ROOT    Set deno install's output directory
                         (defaults to $HOME/.deno/bin)
    NO_COLOR             Set to disable color
    HTTP_PROXY           Proxy address for HTTP requests
                         (module downloads, fetch)
    HTTPS_PROXY          Same but for HTTPS

The Deno commands

Note the SUBCOMMANDS section in the help, that lists all the commands we can run. What subcommands do we have?

bundle bundle module and dependencies of a project into single file
cache cache the dependencies
completions generate shell completions
doc show documentation for a module
eval to evaluate a piece of code, e.g. deno eval "console.log(1 + 2)"
fmt a built-in code formatter (similar to gofmt in Go)
help prints this message or the help of the given subcommand(s)
info show info about cache or info related to source file
install install script as an executable
repl Read-Eval-Print-Loop (the default)
run run a program given a filename or url to the module
test run tests
types print runtime TypeScript declarations
upgrade upgrade deno to the newest version

You can run deno help to get specific additional documentation for the command, for example deno run --help.

As the help says, we can use this command to start a REPL (Read-Execute-Print-Loop) using deno without any other option.

This is the same as running deno repl.

A more common way you’ll use this command is to execute a Deno app contained in a TypeScript file.

You can run both TypeScript (.ts) files, or JavaScript (.js) files.

If you are unfamiliar with TypeScript, don’t worry: Deno is written in TypeScript, buf you can write your “client” applications in JavaScript.

My TypeScript tutorial will help you get up and running quickly with TypeScript if you want.

Your first Deno app

Let’s run a Deno app for the first time.

What I find pretty amazing is that you don’t even have to write a single line - you can run a command from any URL.

Deno downloads the program, compiles it and then runs it:

Of course running arbitrary code from the Internet is not a practice I'd generally recommend. In this case we are running it from the Deno official site, plus Deno has a sandbox that prevents programs to do anything you don’t want to allow. More on this later.

This program is very simple, just a console.log() call:

console.log('Welcome to Deno ?')

If you open the https://deno.land/std/examples/welcome.ts URL with the browser, you’ll see this page:

Weird, right? You’d probably expect a TypeScript file, but instead we have a web page. The reason is the Web server of the Deno website knows you’re using a browser and serves you a more user friendly page.

Download the same UR using wget for example, which requests the text/plain version of it instead of text/html:

If you want to run the program again, it’s now cached by Deno and it does not need to download it again:

You can force a reload of the original source with the --reload flag:

deno run has lots of different options that were not listed in the deno --help. Instead, you need to run deno run --help to reveal them:

flavio@mbp~> deno run --help
deno-run
Run a program given a filename or url to the module.

By default all programs are run in sandbox without access to disk, network or
ability to spawn subprocesses.
  deno run https://deno.land/std/examples/welcome.ts

Grant all permissions:
  deno run -A https://deno.land/std/http/file_server.ts

Grant permission to read from disk and listen to network:
  deno run --allow-read --allow-net https://deno.land/std/http/file_server.ts

Grant permission to read whitelisted files from disk:
  deno run --allow-read=/etc https://deno.land/std/http/file_server.ts

USAGE:
    deno run [OPTIONS] ...

OPTIONS:
    -A, --allow-all
            Allow all permissions

        --allow-env
            Allow environment access

        --allow-hrtime
            Allow high resolution time measurement

        --allow-net=
            Allow network access

        --allow-plugin
            Allow loading plugins

        --allow-read=
            Allow file system read access

        --allow-run
            Allow running subprocesses

        --allow-write=
            Allow file system write access

        --cached-only
            Require that remote dependencies are already cached

        --cert 
            Load certificate authority from PEM encoded file

    -c, --config 
            Load tsconfig.json configuration file

    -h, --help
            Prints help information

        --importmap 
            UNSTABLE:
            Load import map file
            Docs: https://deno.land/std/manual.md#import-maps
            Specification: https://wicg.github.io/import-maps/
            Examples: https://github.com/WICG/import-maps#the-import-map
        --inspect=
            activate inspector on host:port (default: 127.0.0.1:9229)

        --inspect-brk=
            activate inspector on host:port and break at start of user script

        --lock 
            Check the specified lock file

        --lock-write
            Write lock file. Use with --lock.

    -L, --log-level 
            Set log level [possible values: debug, info]

        --no-remote
            Do not resolve remote modules

    -q, --quiet
            Suppress diagnostic output
            By default, subcommands print human-readable diagnostic messages to stderr.
            If the flag is set, restrict these messages to errors.
    -r, --reload=
            Reload source code cache (recompile TypeScript)
            --reload
              Reload everything
            --reload=https://deno.land/std
              Reload only standard modules
            --reload=https://deno.land/std/fs/utils.ts,https://deno.land/std/fmt/colors.ts
              Reloads specific modules
        --seed 
            Seed Math.random()

        --unstable
            Enable unstable APIs

        --v8-flags=
            Set V8 command line options. For help: --v8-flags=--help


ARGS:
    ...
            script args

Deno code examples

In addition to the one we ran above, the Deno website provides some other examples you can check out: https://deno.land/std/examples/.

At the time of writing we can find:

cat.ts prints the content a list of files provided as arguments
catj.ts prints the content a list of files provided as arguments
chat/ an implementation of a chat
colors.ts an example of
curl.ts a simple implementation of curl that prints the content of the URL specified as argument
echo_server.ts a TCP echo server
gist.ts a program to post files to gist.github.com
test.ts a sample test suite
welcome.ts a simple console.log statement (the first program we ran above)
xeval.ts allows you to run any TypeScript code for any line of standard input received. Once known as deno xeval but since removed from the official command.

Your first Deno app (for real)

Let’s write some code.

Your first Deno app you ran using deno run https://deno.land/std/examples/welcome.ts was an app that someone else wrote, so you didn’t see anything in regards to how Deno code looks like.

We’ll start from the default example app listed on the Deno official website:

import { serve } from 'https://deno.land/std/http/server.ts'
const s = serve({ port: 8000 })
console.log('http://localhost:8000/')
for await (const req of s) {
  req.respond({ body: 'Hello World\n' })
}

This code imports the serve function from the http/server module. See? We don’t have to install it first, and it’s also not stored on your local machine like it happens with Node modules. This is one reason why the Deno installation was so fast.

Importing from https://deno.land/std/http/server.ts imports the latest version of the module. You can import a specific version using @VERSION, like this:

import { serve } from 'https://deno.land/std@v0.42.0/http/server.ts'

The serve function is defined like this in this file:

/**
 * Create a HTTP server
 *
 *     import { serve } from "https://deno.land/std/http/server.ts";
 *     const body = "Hello World\n";
 *     const s = serve({ port: 8000 });
 *     for await (const req of s) {
 *       req.respond({ body });
 *     }
 */
export function serve(addr: string | HTTPOptions): Server {
  if (typeof addr === 'string') {
    const [hostname, port] = addr.split(':')
    addr = { hostname, port: Number(port) }
  }

  const listener = listen(addr)
  return new Server(listener)
}

We proceed to instantiate a server calling the serve() function passing an object with the port property.

Then we run this loop to respond to every request coming from the server.

for await (const req of s) {
  req.respond({ body: 'Hello World\n' })
}

Note that we use the await keyword without having to wrap it into an async function because Deno implements top-level await.

Let’s run this program locally. I assume you use VS Code, but you can use any editor you like.

I recommend installing the Deno extension from justjavac (there was another one with the same name when I tried, but deprecated - might disappear in the future)

The extension will provide several utilities and nice thing to VS Code to help you write your apps.

Now create an app.ts file in a folder and paste the above code:

Now run it using deno run app.ts:

Deno downloads all the dependencies it needs, by first downloading the one we imported.

The https://deno.land/std/http/server.ts file has several dependencies on its own:

import { encode } from '../encoding/utf8.ts'
import { BufReader, BufWriter } from '../io/bufio.ts'
import { assert } from '../testing/asserts.ts'
import { deferred, Deferred, MuxAsyncIterator } from '../async/mod.ts'
import {
  bodyReader,
  chunkedBodyReader,
  emptyReader,
  writeResponse,
  readRequest,
} from './_io.ts'
import Listener = Deno.Listener
import Conn = Deno.Conn
import Reader = Deno.Reader

and those are imported automatically.

At the end though we have a problem:

What is happening? We have a permission denied problem.

Let’s talk about the sandbox.

The Deno sandbox

I mentioned previously that Deno has a sandbox that prevents programs from doing anything you don’t want to allow.

What does this mean?

One of the things that Ryan mentions in the Deno introduction talk is that sometimes you want to run a JavaScript program outside of the Web Browser, and yet do not want allow it to access to anything it wants on your system. Or talk to the external world using a network.

There’s nothing stopping a Node.js app from getting your SSH keys or any other thing on your system and sending it to a server. This is why we usually only install Node packages from trusted sources. But how can we know if one of the projects we use gets hacked and in turn everyone else does?

Deno tries to replicate the same permission model that the browser implements. No JavaScript running in the browser can do shady things on your system unless you explicitly allow it.

Going back to Deno, if a program want to access the network like in the previous case, then we need to give it permission.

We can do so by passing a flag when we run the command, in this case --allow-net:

deno run --allow-net app.ts

The app is now running an HTTP server on port 8000:

Other flags allow Deno to unlock other functionality:

--allow-env allow environment access
--allow-hrtime allow high resolution time measurement
--allow-net= allow network access
--allow-plugin allow loading plugins
--allow-read= allow file system read access
--allow-run allow running subprocesses
--allow-write= allow file system write access
--allow-all allow all permissions (same as -A)

Permissions for net, read and write can be granular. For example, you can allow reading from a specific folder using --allow-read=/dev

Formatting code

One of the things I really liked from Go was the gofmt command that came with the Go compiler. All Go code looks the same. Everyone uses gofmt.

JavaScript programmers are used to running Prettier, and deno fmt actually runs that under the hood.

Say you have a file formatted badly like this:

You run deno fmt app.ts and it’s automatically formatted properly, also adding semicolons where missing:

The standard library

The Deno standard library is extensive despite the project being very young.

It includes:

archive tar archive utilities
async async utilties
bytes helpers to manipulate bytes slices
datetime date/time parsing
encoding encoding/decoding for various formats
flags parse command-line flags
fmt formatting and printing
fs file system API
hash crypto lib
http HTTP server
io I/O lib
log logging utilities
mime support for multipart data
node Node.js compatibility layer
path path manipulation
ws websockets

Another Deno example

Let’s see another example of a Deno app, from the Deno examples: cat:

const filenames = Deno.args
for (const filename of filenames) {
  const file = await Deno.open(filename)
  await Deno.copy(file, Deno.stdout)
  file.close()
}

This assigns to the filenames variable the content of Deno.args, which is a variable containing all the arguments sent to the command.

We iterate through them, and for each we use Deno.open() to open the file and we use Deno.copy() to print the content of the file to Deno.stdout. Finally we close the file.

If you run this using

deno run https://deno.land/std/examples/cat.ts

The program is downloaded and compiled, and nothing happens because we didn’t specify any argument.

Try now

deno run https://deno.land/std/examples/cat.ts app.ts

assuming you have app.ts from the previous project in the same folder.

You’ll get a permission error:

Because Deno disallows access to the filesystem by default. Grant access to the current folder using --allow-read=./:

deno run --allow-read=./ https://deno.land/std/examples/cat.ts app.ts

Is there an Express/Hapi/Koa/* for Deno?

Yes, definitely. Check out projects like

Example: use Oak to build a REST API

I want to make a simple example of how to build a REST API using Oak. Oak is interesting because it’s inspired by Koa, the popular Node.js middleware, and due to this it’s very familiar if you’ve used that before.

The API we’re going to build is very simple.

Our server will store, in memory, a list of dogs with name and age.

We want to:

add new dogs
list dogs
get details about a specific dog
remove a dog from the list
update a dog's age

We’ll do this in TypeScript, but nothing stops you from writing the API in JavaScript - you simply remove the types.

Create a app.ts file.

Let’s start by importing the Application and Router objects from Oak:

import { Application, Router } from 'https://deno.land/x/oak/mod.ts'

then we get the environment variables PORT and HOST:

const env = Deno.env.toObject()
const PORT = env.PORT || 4000
const HOST = env.HOST || '127.0.0.1'

By default our app will run on localhost:4000.

Now we create the Oak application and we start it:

const router = new Router()

const app = new Application()

app.use(router.routes())
app.use(router.allowedMethods())

console.log(`Listening on port ${PORT}...`)

await app.listen(`${HOST}:${PORT}`)

Now the app should be compiling fine.

Run

deno run --allow-env --allow-net app.ts

and Deno will download the dependencies:

and then listen on port 4000.

The next times you run the command, Deno will skip the installation part because those packages are already cached:

At the top of the file, let’s define an interface for a dog, then we declare an initial dogs array of Dog objects:

interface Dog {
  name: string
  age: number
}

let dogs: Array = [
  {
    name: 'Roger',
    age: 8,
  },
  {
    name: 'Syd',
    age: 7,
  },
]

Now let’s actually implement the API.

We have everything in place. After you create the router, let’s add some functions that will be invoked any time one of those endpoints is hit:

const router = new Router()

router
  .get('/dogs', getDogs)
  .get('/dogs/:name', getDog)
  .post('/dogs', addDog)
  .put('/dogs/:name', updateDog)
  .delete('/dogs/:name', removeDog)

See? We define

GET /dogs
GET /dogs/:name
POST /dogs
PUT /dogs/:name
DELETE /dogs/:name

Let’s implement those one-by-one.

Starting from GET /dogs, which returns the list of all the dogs:

export const getDogs = ({ response }: { response: any }) => {
  response.body = dogs
}

Next, here’s how we can retrieve a single dog by name:

export const getDog = ({
  params,
  response,
}: {
  params: {
    name: string
  }
  response: any
}) => {
  const dog = dogs.filter((dog) => dog.name === params.name)
  if (dog.length) {
    response.status = 200
    response.body = dog[0]
    return
  }

  response.status = 400
  response.body = { msg: `Cannot find dog ${params.name}` }
}

Here is how we add a new dog:

export const addDog = async ({
  request,
  response,
}: {
  request: any
  response: any
}) => {
  const body = await request.body()
  const dog: Dog = body.value
  dogs.push(dog)

  response.body = { msg: 'OK' }
  response.status = 200
}

Notice that I now used const body = await request.body() to get the content of the body, since the name and age values are passed as JSON.

Here’s how we update a dog’s age:

export const updateDog = async ({
  params,
  request,
  response,
}: {
  params: {
    name: string
  }
  request: any
  response: any
}) => {
  const temp = dogs.filter((existingDog) => existingDog.name === params.name)
  const body = await request.body()
  const { age }: { age: number } = body.value

  if (temp.length) {
    temp[0].age = age
    response.status = 200
    response.body = { msg: 'OK' }
    return
  }

  response.status = 400
  response.body = { msg: `Cannot find dog ${params.name}` }
}

and here is how we can remove a dog from our list:

export const removeDog = ({
  params,
  response,
}: {
  params: {
    name: string
  }
  response: any
}) => {
  const lengthBefore = dogs.length
  dogs = dogs.filter((dog) => dog.name !== params.name)

  if (dogs.length === lengthBefore) {
    response.status = 400
    response.body = { msg: `Cannot find dog ${params.name}` }
    return
  }

  response.body = { msg: 'OK' }
  response.status = 200
}

Here’s the complete example code:

import { Application, Router } from 'https://deno.land/x/oak/mod.ts'

const env = Deno.env.toObject()
const PORT = env.PORT || 4000
const HOST = env.HOST || '127.0.0.1'

interface Dog {
  name: string
  age: number
}

let dogs: Array = [
  {
    name: 'Roger',
    age: 8,
  },
  {
    name: 'Syd',
    age: 7,
  },
]

export const getDogs = ({ response }: { response: any }) => {
  response.body = dogs
}

export const getDog = ({
  params,
  response,
}: {
  params: {
    name: string
  }
  response: any
}) => {
  const dog = dogs.filter((dog) => dog.name === params.name)
  if (dog.length) {
    response.status = 200
    response.body = dog[0]
    return
  }

  response.status = 400
  response.body = { msg: `Cannot find dog ${params.name}` }
}

export const addDog = async ({
  request,
  response,
}: {
  request: any
  response: any
}) => {
  const body = await request.body()
  const { name, age }: { name: string; age: number } = body.value
  dogs.push({
    name: name,
    age: age,
  })

  response.body = { msg: 'OK' }
  response.status = 200
}

export const updateDog = async ({
  params,
  request,
  response,
}: {
  params: {
    name: string
  }
  request: any
  response: any
}) => {
  const temp = dogs.filter((existingDog) => existingDog.name === params.name)
  const body = await request.body()
  const { age }: { age: number } = body.value

  if (temp.length) {
    temp[0].age = age
    response.status = 200
    response.body = { msg: 'OK' }
    return
  }

  response.status = 400
  response.body = { msg: `Cannot find dog ${params.name}` }
}

export const removeDog = ({
  params,
  response,
}: {
  params: {
    name: string
  }
  response: any
}) => {
  const lengthBefore = dogs.length
  dogs = dogs.filter((dog) => dog.name !== params.name)

  if (dogs.length === lengthBefore) {
    response.status = 400
    response.body = { msg: `Cannot find dog ${params.name}` }
    return
  }

  response.body = { msg: 'OK' }
  response.status = 200
}

const router = new Router()
router
  .get('/dogs', getDogs)
  .get('/dogs/:name', getDog)
  .post('/dogs', addDog)
  .put('/dogs/:name', updateDog)
  .delete('/dogs/:name', removeDog)

const app = new Application()

app.use(router.routes())
app.use(router.allowedMethods())

console.log(`Listening on port ${PORT}...`)

await app.listen(`${HOST}:${PORT}`)

Find out more

The Deno official website is https://deno.land

The API documentation is available at https://doc.deno.land and https://deno.land/typedoc/index.html

awesome-deno https://github.com/denolib/awesome-deno

A few more random tidbits

Deno provides a built-in fetch implementation that matches the one available in the browser
Deno has a compatibility layer with the Node.js stdlib in progress

Final words

I hope you enjoyed this Deno tutorial!

Reminder: You can get a PDF/ePub/Mobi version of this Deno Handbook here.

Deno - freeCodeCamp.org

Lume SSG Handbook – How to Create a Static Blog with Lume

What is Deno?

Table of Contents

Lume + Markdown

Why is Lume special?

How Does Lume Compare to Other Static Site Generators?

How to Start a New Project with Lume

Follow these steps:

Lume Folder Structure

How to run the Lume server

Additional folders:

How to Create Global Data

How to create posts, pages, and author markdown files

How to create a dynamic page

How to create a home and pagination page

Posts is empty

How to Build an Articles Page

{{ title }}

Comment

How to Generate a Category Page

How to Generate a Tag Page

How to Enable Search Functionality

How to Install Page Find

How to configure the page find plugin

Lume SEO

How to install metas

How to configure metas

How to Use the Metas SEO Plugin in Lume

Lume Sitemap

How to install the sitemap plugin

How to configure the sitemap plugin

How to use the sitemap plugin in Lume

How to access the sitemap on the website

Lume Plugins

How to Enable Comments

How to Use Netlify CMS with Lume

How to Install the Netlify Plugin

How to Deploy Your Blog with Deno Deploy

Deployment Steps:

How to Deploy Your Blog with Github Pages

Deployment Steps

Conclusion

How to Use SurrealDb with the Fresh Framework and Deno

Here's a Demo of What We'll be Building:

How to Install SurrealDB, Deno, and the Fresh Framework

How to Install the SurrealDB database on Linux

How to Install Deno on Linux

How to Install the Fresh Framework with Deno

Fresh Framework Project Structure

How to Install the SurrealDB Database Library in the Fresh Framework

How to Setup the SurrealDB Database in Fresh

How to Use SurrealDB Module (Library) Methods

How to Create the API Endpoints

The Get API

The Post API

The Isdone (Update) API

The Delete API

How to Create the UI for the Todo App

Index page

class="m-2 p-1 text-5xl font-mono font-serif cursor-pointer">Deno

class="m-2 p-1 text-5xl font-mono font-serif cursor-pointer">SurrealDB

class="text-gray-500 text-lg">Todo List

The Box.tsx Component

The Item.tsx Component

Conclusion

How to Create a Static Markdown Blog with Deno and Deploy It

What is markdown?

Here are the steps we'll follow:

How to Install and Setup the Blog

How to Understand the Folder Structure

How to Start the Local Developer Server

How to Add More Configuration to the Blog

Custom configuration

How to Deploy Your Blog with Deno

Deployment steps:

Login to your account on Deno deploy

Click to create a new project

Configure the GitHub repository and environment variables

Deployment is finished