DEV Community: Guilherme Guerreiro

I've made a Blog using the Fresh Framework

Guilherme Guerreiro — Mon, 11 Jul 2022 09:31:07 +0000

Web development frameworks have been around for a while now, and they help solve many difficulties that would be hard to surpass if we were to make web applications using nothing but HTML templates or vanilla Javascript but, it also seems that a new framework appears every week which promises the world and more. Well, Fresh framework is something like that, but with a tiny twist which makes it interesting to try out.

In a nutshell, Fresh framework is a full-stack web framework that considers itself "The next-gen web framework" with some neat features:

Just-in-time rendering
Island based client hydration
Zero runtime overhead
No build step
No configuration
TypeScript support

What makes it even more interesting is that it was made by Deno so, obviously, is running on top of it. I'm not going too much in detail about what Deno is but consider it the faster replacement for Node.js which also promises a bunch of stuff.

If you're interested in finding more about these two I'll leave you with some links you can check out later:

Fresh Framework: https://fresh.deno.dev/
Deno: https://deno.land/

Creating the Blog

I've decided to take up the challenge and build a markdown blog using this new framework. In order to make such blog, I had two things in mind right from the start:

I must be able to read markdown files directly from my filesystem.
I must be able to parse the markdown text into HTML elements.

To start the project I've followed the standard procedure shown in the Fresh website. Simply have Deno CLI installed and run deno run -A -r https://fresh.deno.dev my-blog, choose your configuration and... puff! a project is created. Now navigate to the root folder of the project and run deno task start. You have now a Fresh Framework project up and running!

This comes with some code examples you can go through but, essentially, you must be aware of two folders it creates: routes and islands. These folders are the essence of Fresh and you should know what they do:

routes: this is where you structure your code and create your routes. Basically, the name of every file you create in this folder is going to be a route path. So, if you create a file called "blog.tsx", the code displayed in there will the accessible through the path https://localhost:8000/blog. The same happens with the folders inside, if you have a folder called api and a file named jokes.ts inside of it, you can access it through the path https://localhost:8000/api/jokes. To make dynamic routes simply have your file or folder name inside [] and access the parameter using props.params.[name].
islands: this is where you store your code that requires Javascript to run. So, all code that must be changed or manipulated during the usage of your page must go in here. What Fresh does special is that it only uses Javascript when compiling your project for the code you have inside of this folder, the rest of it that is inside of the routes folder is rendered as a pure HTML template.

Ok, let's get ready for some coding shall we?

Folder structure

You can make your blog anyway you want, as long as you can read files and parse markdown you are good to go! But, if you want to follow my example, you can have your folders structure. There are more files on my project but I just want to display the most important ones:

├── routes
│   ├── [section]
│   │   ├── [title].tsx
|   |   ├── index.tsx
│   ├── index.tsx
├── islands
│   ├── Post.tsx
├── components
│   ├── Content.tsx
│   ├── Footer.tsx
│   ├── Navbar.tsx
├── styles
│   ├── main.css
├── posts
│   ├── section
│   ├── ├── post.md
├── utils
│   ├── locate.ts
│   ├── twind.ts

Reading files

Deno does not use your typical Node.js modules so, obviously, reading files will be a bit different as well. Fortunately, Deno makes it easy by providing these functions straight out of the box using the built-in module Deno.

Since I created sections for my posts, I must first know the sections and, afterwards, read the files inside each one. My idea was to create an object with all the information I needed and pass it through the props directly into my page. The object looks something like this:

{
  <section>: [
    {
      url: <string>
      title: <string>
      date: <Date | string>
    },
    ...
  ],
  ...
}

Where section is the name of my folders, url the name of my files, title the first h1 tag of the file and date the creation date of the file. I use this object to display all my posts in my home page.

To read the directories inside of my posts folder I've used the Deno.readDir function and created a function to store them in an object and initialize each of them with an empty array.

/* locate.ts */

export async function createObj() {
  const obj: PostsType = {};
  for await (const dir of Deno.readDir("./posts")) {
    if (dir.isDirectory) obj[dir.name] = [];
  }

  return obj;
}

Afterwards, I must go through each of these sections and actually store the file information in the array. To do this I've used the previous function to search through the directory but also Deno.readFile to read the file and Deno.stat to get some of the file's information such as birthtime. I've created a function that returns an object array for each of the sections.

/* locate.ts */

export async function getPosts(dir: string) {
  const posts: [PostType?] = [];

  for await (const post of Deno.readDir(`./posts/${dir}`)) {
    const path = `./posts/${dir}/${post.name}`;
    const { birthtime } = await Deno.stat(path);
    const file = await Deno.readTextFile(path);
    const firstLine = file.split("\n")[0];

    if (post.isFile) {
      const payload = {url: post.name.split(".md")[0], title: firstLine.slice(2, firstLine.length), date: birthtime}
      posts.push(payload);
    }
  }

  return posts;
}

You must use async await with these functions because, although Deno provides a synchronous way for each of these, when deploying it complains about them.

Parse the markdown

First objective accomplished! Now it's time for the final one which is parsing the markdown text into HTML elements. To do this, Deno has a nice module library called gfm. To use it, change your import_map.json file and add an extra line "gfm": "https://deno.land/x/gfm@0.1.22/mod.ts". You can now import this module on any file with import * as gfm from "gfm".

I must parse the markdown before the page renders so, I've used a middleware handler for this.

/* [title].tsx */

/** @jsx h */
import { h } from "preact";
import { PageProps, Handlers } from "$fresh/server.ts";
import { render } from "gfm";

export const handler: Handlers = {
  async GET(req, ctx) {
    const url = new URL(req.url).pathname.split('/')
    const file = url[2]
    const section = url[1]

    const decoder = new TextDecoder("utf-8");
    const markdown = decoder.decode(await Deno.readFile(`./posts/${section}/${file}.md`));
    const markup = render(markdown)

    return ctx.render({ markup: markup })
  },
};

In essence, I fetch my section and file name through my url, read the file which is located in the path ./posts/${section}/${file}.md and decode it using the TextDecoder. I then parse the markdown into HTML string using the render function. I then render the page using ctx.render with the generated string inside as an object { markup: markup }. You can then retrieve this content in your page by using props.data.markup.

/* [title].tsx */

export default function MarkdownPost(props: PageProps) {
  return (  
    <main>
      <article>
        <Post markup={props.data.markup} />
      </article>
    </main>
  );
}

You can see in the code above that I'm using a component inside of the article tag. Well, this is my only island component and I must do this because, unfortunately, Fresh does not provide (or at least does not explain how to do it) a way to insert HTML elements into my page before rendering, so I must use some DOM manipulation to change my HTML string into actual elements.

/* Post.tsx */

/** @jsx h */
import { h } from "preact";
import { useRef, useLayoutEffect } from "preact/hooks";

interface PostProps {
  markup: string;
}

export default function Post(props: PostProps) {
  const el = useRef<HTMLDivElement>(null)

  useLayoutEffect(() => {
    if (el.current) {
      el.current.innerHTML = props.markup
    }
  })

  return (
    <div data-color-mode="light" data-light-theme="light" data-dark-theme="dark" class="markdown-body" ref={el} ></div>
  );
}

In this file, I'm using the useRef hook to get the div element and the useLayoutEffect to manipulate that element before the page renders and insert my HTML string inside of the element's innerHTML which, luckly, takes a string. This will insert all of my markdown generated HTML inside of the div element I have my ref on.

Displaying all of my posts in the Home page

I now have my posts being shown on their specific url but how about selecting which post to go? In your index.tsx file, create a new handler to run some code before rendering the page. In here, we will create our posts object using the functions we previously coded inside our locate.ts file.

/* index.tsx */

/** @jsx h */
import { h } from "preact";
import { Handlers, PageProps } from "$fresh/server.ts";
import { PostsType, getPosts, createObj } from '../utils/locate.ts'

export const handler: Handlers = {
  async GET(_, ctx) {
    const posts: PostsType = await createObj();

    for (const dir of Object.keys(posts)) {
      posts[dir] = await getPosts(dir);
    }

    return ctx.render({ posts });
  },
};

We created our object with our sections using the createObj function and then, for each section, we fetched the posts using the getPosts function. We send this newly created object to our page using the ctx.render. Now we want to go through every post and display it on the screen.

/* index.tsx */

export default function Home(props: PageProps) {
  return (
    <main>
      <Content posts={props.data.posts} />
    </main>
  );
}

/* Content.tsx */

/** @jsx h */
import { h } from "preact";
import { tw } from "twind"
import { PostsType } from '../utils/locate.ts'

interface ContentProps {
  posts: PostsType;
}

export default function Content(props: ContentProps) {
  return (
    <section>
      <div>
        {Object.entries(props.posts).map(([key, value]) =>
          value.map((post) => {
            return (
              <a href={`/${key}/${post?.url}`}>
                <div>
                  <span>{key}</span>
                  <h3>{post?.title}</h3>
                </div>
              </a>
            );
          })
        )}
      </div>
    </section>
  );
}

We go through every entry on our object, and map through the value array to display the section and title of the post. We then use an a tag to navigate to the desired post by giving it the path /${key}/${post?.url}.

All done! Now you have your home page displaying all posts and a page for each post displaying the content of your markdown!

Styling

I won't go through how I've styled my blog (you can check it out in my source code if you want) but I must go through a basic thing among web frameworks that Fresh made a bit harder to find which is: importing a .css file into our pages. I wanted to style my markdown background color and other useful content so I got a stylesheet. But, unfortunately, you can't just do import "./styles/markdown.css" in your code. The easiest way I found was to change the main.ts file and add a few extra lines to it. Note that I'm using the twin module but you could do this without it as well.

In here, I'm also importing CSS from gfm module to style my markdown elements. This loads the necessary styles into my page.

/* main.ts */

/// <reference no-default-lib="true" />
/// <reference lib="dom" />
/// <reference lib="dom.asynciterable" />
/// <reference lib="deno.ns" />
/// <reference lib="deno.unstable" />

import { InnerRenderFunction, RenderContext, start } from "$fresh/server.ts";
import manifest from "./fresh.gen.ts";

import { config, setup } from "@twind";
import { CSS } from 'gfm'
import { virtualSheet } from "twind/sheets";

const sheet = virtualSheet();
sheet.reset();
setup({ ...config, sheet });

const stylesheet = await Deno.readTextFile("./styles/markdown.css");

function render(ctx: RenderContext, render: InnerRenderFunction) {
  const snapshot = ctx.state.get("twind") as unknown[] | null;
  sheet.reset(snapshot || undefined);
  render();
  ctx.styles.splice(0, ctx.styles.length, ...(sheet).target, CSS, stylesheet);
  const newSnapshot = sheet.reset();
  ctx.state.set("twind", newSnapshot);
}

First I must read the file as text using Deno.readTextFile and store it in a constant. Afterwards, I must send it in the ctx.styles alongside the rest of the styles.

Performance

What Fresh really does well it's boosting performance and I've checked that through Google's Lighthouse extension which generates a report with all these metrics tested.

As you can see, the performance is at 100%, which is pretty good if you ask me!

Final review of Fresh

This framework provides some cool concepts that are definitely interesting and aim to solve some of the performance issues other frameworks have but it lacks in other aspects:

Poor documentation: I know it's a very new framework and therefore we should not expect it to have as much of a documentation and community guidance as other more popular frameworks but the official documentation lacks information in several aspects, making the developer search by itself or just randomly trying out things without any knowledge of the outcome.
Reuse of components: I'm sure there must be a way to do this but, sometimes we want to have a template loaded for every page which can contain things like a navbar or footer but Fresh does not provide us this and, if it does, is very well hidden and, again, not documented.
Deno modules: some people might hate me for this but Deno modules are definitely not as strong, at the moment, as Node.js ones which makes it harder to develop a web applications with them.
Styles: not being able to import a stylesheet is a big downside. I had to go through some search before I could figure out how to actually do this an, even so, I don't think I'm doing a really good job with it but, hey!, it works!
Page Refresh: because it compiles your code into pure HTML, it also means your pages must reload when switching url. Although one-page web applications are slower in terms of performance, the flow it provides afterwards is refreshing.

Overall, Fresh framework has a long way to go in order to fight against more popular full-stack frameworks and definitely needs some improvements in the above issues or, at least, give us the documentation to know how to surpass them!

Would I use it to build big web applications? - No
Is it easy to pick-up? - Yes
Would I use it to build simple websites? - Depends on the dependencies

If you want to explore more, check out my source code: https://github.com/Guiguerreiro39/fresh-blog

The blog is deployed with Deno Deploy at https://gg-blog.deno.dev/ but proxied to my own domain at https://blog.guilhermegr.com.

That's all for now! See ya!

How to Integrate Tailwindcss with your Vue/Vite Project

Guilherme Guerreiro — Fri, 16 Oct 2020 10:46:50 +0000

In this post I'll show you how to integrate and configure Tailwindcss in a Vue project! I'll also be using Vite instead of vue-cli!

Why Tailwind?

Css frameworks have been around for quite a while now and are widly used around the internet. You may have heard or even used frameworks such as Bootstrap or Foundation, which are quite useful if you want to build a fast and somehow good looking application.

The problem with these types of css frameworks is that they are considered to be high-level, meaning that they are meant to style components according to their specifications. This is somehow of a problem because if you want to customize your front-end you might have to create a new css file and overwritte most of the classes that the framework provides, which is tiresome and annoying at best!

To tackle this, Tailwindcss was created which in their words is "a highly customizable, low-level CSS framework" making it possible to add personal styling without the need to override any type of component.

Setting up a Vite Project

A Vite project can easily be started by just typing in your terminal or command line npm init vite-app . Just by doing this you can see how fast and powerful Vite is!

After the setup just follow the next few commands to install all the dependencies and run your project for the first time. And that's it! You now have a brand new Vite project! Open it now in your favorite IDE and let's start!

Setting up Taildwind CSS

It's now time for the main event! To install tailwind simply run the command npm i tailwindcss. After the instalation a few configurations are needed in order to start using it in your project!

First create a new css file. This can be placed and named anything so to simplify I'll name mine tailwind.css and store it in the project src directory. After creating, write the following inside the file:

@tailwind base;
@tailwind components;
@tailwind utilities;

This will load on build time all the tailwindcss classes into your css file!

Next we need to create a config file for tailwind and postcss (since tailwindcss uses postcss) to customize as much as we want if necessary! To do so simply run npx tailwindcss init -p. As you might notice, two new files, tailwind.config.js and postcss.config.js were created in your project root folder.

Finally just change the postcss.config.js file like so:

module.exports = {
  plugins: [
    require("tailwindcss"), 
    require("autoprefixer")
  ],
};

This will load tailwindcss and autoprefixer into postcss. Vite also has a cool feature that automatically loads my postcss config into all my styles in *.vue and imported plain .css files!

Finally, let's import tailwind.css file into our main.js by adding import "./tailwind.css" into the file and let's check out if everything is working accordingly!

To check if tailwindcss is up and running in our application let's add some classes into our HelloWorld.vue file.

<template>
  <h1 class="text-red-500 bg-blue-500">{{ msg }}</h1>
  <button @click="count++" class="p-4 bg-green-600 rounded-full">count is: {{ count }}</button>
  <p>Edit <code>components/HelloWorld.vue</code> to test hot module replacement.</p>
</template>

The text-red-500 will set the h1 color to a light red and bg-blue-500 will simply add a blue background color to the h1.
I've also added some classes in the button. The p-4 class adds padding in all directions to the button and bg-green-600 gives a nice green background. Finally the rounded-full class will fully round the button!

Awesome! Everything is working and now we can start using the amazing functionalities that tailwindcss provides! Have fun exploring Tailwind! If you want to take a look at all the possible classes check out their documentation!

Hacktoberfest! 4PRs done and what I've learn!

Guilherme Guerreiro — Tue, 13 Oct 2020 18:49:14 +0000

It's been a week since I've stumbled across Hacktoberfest and, let me say it, it's been nothing but a great and pleasant ride..!!

To be honest, I've never actually considered writting code for another person's project but this new experience openned my eyes to the amazing world of open source!

I started this challenge with no to little expectation of how would it go and if I would even finish it. 4 pull requests later, here I stand in my new favorite thing, DEV, posting about a challenge I knew nothing about!

I started off by simply searching in github for literally anything that had the tag "hacktoberfest" and I stumbled apon a few THOUSAND issues! I had no idea where to start so I started with some basic frontend features just to get used to the whole issue/PR vibe. I must say it felt amazing when my first pull request was accepted and a random guy just told me "Great job! Thanks for contributing!". This gave me the energy and motivation to keep going and to find new and challenging issues!

Not everything was a piece of cake though.. I had times where I was working on a project written in Swift, which I know nothing about.. (serious, I had to wiki Swift just to know what that was!) So, really bad idea to get into something I had absolutely no experience on.. At the end of the day I just gave up on that issue and started working on something else.

The days passed and my pull requests were starting to get accepted more and more! I've made it to the end of Hacktoberfest! I must say, this experience was way more enjoyable than I ever thought and I'll definetely keep on contributing for the open source community and perhaps join it with one of my personal projects myself!

That's about it for this post! Thank you for reading and have a fantastic day! Cheers!