Forem: Rui Sousa

How to build a blog with NodeJS

Rui Sousa — Thu, 31 Oct 2024 17:02:21 +0000

Just want the code? Visit the repo

If you're looking to start a blog (or if you're thinking of redesigning yours although you haven't posted in 2 years), you'll stumble upon a lot of options and it can be incredibly daunting; and if you stumble with the newest Josh's post about his stack it is easy to feel overwhelmed with the shown stack.

But you shouldn't feel like that and starting small is key to being sustainable

And how do I know that? Because I feel that sense of feeling overwhelmed as well!
At this date, this website is done with NextJS, Contentful, and Markdown and while adding posts to it is not particularly hard, maintaining it is!

I haven't added anything code-related to this website since 2021 and at this point I don't even know if I'm able to run it locally (and I'm reticent even to try it out)!

For this 👆 particular reason, I want to preach for a simple stack; something that endures the test of time; something that 'just works'; so let's jump right into it, shall we?

Start that project!

Keep in mind that this project will be very, very barebones but it should give you a good foundation for you to develop on top of it and reach for the sky.

We'll start by initializing a Node project inside a chosen folder (nodejs-blog for me) with and installing a couple of dependencies that I feel like will make our lives easier, like Express, EJS, Marked, the good ol' body-parser and gray-matter.

npm init
npm install body-parser ejs express marked gray-matter

Explaining the dependencies

The reason why I chose to add EJS into the mix was to make things a bit easier for me, by taking advantage of templates and just writing less code overall. If you're not familiar with it, just wait. It's pretty cool!

For Marked and gray-matter, it's pretty simple: markdown rules and I want my posts to have proper metadata, which I plan to create with frontmatter.

Alright, back at it!

Now open your project in your favourite IDE and create your main.js file. I know that we'll want the following routes: /, /:post, and that we'll need to have relevant stuff on the public folder, so our initial main.js can look like this:

// main.js
const express = require("express");
const fs = require("fs");
const path = require("path");
const { marked } = require("marked");
const matter = require("gray-matter");

const app = express();
const PORT = process.env.PORT || 3000;

app.use(express.static("public"));
app.set("view engine", "ejs");

app.get("/", (req, res) => {});

app.get("/:post", (req, res) => {});

app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`);
});

Pretty straightforward, right? The idea is to have the list of posts on my home (or /) and just have individual pages for my posts.

Time to template like you never templated before!

With the base setup out of the way, we also need a base structure and EJS will provide that.
Start by creating a folder named views; this will be the root of your pages, so to speak, which means that you can create a home.ejs and a post.ejs inside it just to mark the two types of pages that we'll have.

Create also a folder, inside views, named partials; you can think of it as our components and you can already create 3 files here: header.ejs, footer.ejs and head.ejs.

This is the base structure of our blog: 2 pages and 3 components, that's it. All the rest will be dealt with inside main.js

The `partials`

Like I've mentioned, templates allow us to not have to repeat as much code as we would have to if we were creating each page by hand, and our setup provides us exactly with a ease of mind regarding that.

// head.ejs
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Here's my blog</title>
  </head>
</html>

// footer.ejs
    </main>
  </body>
</html>

// header.ejs
<body>
  <main>
    <header>
      <a href="/">Blog</a>
    </header>

Basically, the regular head at, well, head, the closing tags at footer and the navbar, and opening tags at header. Pretty simple, right?

The `views`

Now that we have our components we can get the pages going.

// home.ejs
<%- include('./partials/head') %>
<%- include('./partials/header') %>
<div>
  <h2>The posts:</h2>
  <ul>
    <% posts.forEach((post)=> { %>
    <li>
      <a href="<%= post.link %>"><%= post.title %></a>
    </li>
    <% }) %>
  </ul>
</div>
<%- include('./partials/footer') %>

// post.ejs
<%- include('./partials/head') %>
<%- include('./partials/header') %>
<h1><%= frontmatter.title %></h1>
<p><%= frontmatter.date %></p>
<p><%= frontmatter.author %></p>
<%- content %>
<%- include('./partials/footer') %>

Yeah, it looks pretty weird but just know that the include brings the partials into our views and that there's extra syntax to make it work (go to the docs if you're interested in how it works).

The <%- allows us to not double-escape our HTML ( try it out with <% or <%= at the end and see what happens) and the forEach(), well, does exactly what a forEach does. Nothing particularly new here, just a different way of writing stuff that you already know!

But, rejoice, you've now interacted with a new tool! 💃

The blog posts! 📄

At the root of your project create a posts folder and your first blog-post-1.md inside of it with the following content:

---
title: "Blog post 1"
date: 2024-10-31
author: "Rui Sousa"
summary: "Here's the first blog post"
---

# A blog post

Here's my first blog post!

What's inside the --- is our frontmatter, and you'll get to use it right away!

Time to see some stuff on the screen!

Back to our main.js, we'll first deal with the / route. As we've seen, we want to be able to get our posts and loop over them to display info about them on the screen.

To simplify stuff I'll leave comments next to each relevant line instead of writing huge blocks of text explaining stuff! 😄

// main.js
app.get("/", (req, res) => {
  // we get the folder with the `posts`
  const postsDir = path.join(__dirname, "posts");
  // we reach inside the folder
  fs.readdir(postsDir, (err, files) => {
    // check for any errors
    if (err) {
      return res.status(500).send("Error reading posts directory");
    }

    const posts = files
       // for the retrieved files we filter those that are markdown `.md`
      .filter((file) => file.endsWith(".md"))
      // afterwards we'll map over each one to parse the info
      .map((file) => {
        // we get its path so we can read its content
        const filePath = path.join(postsDir, file);
        const fileContent = fs.readFileSync(filePath, "utf8");
        // we retrieve the frontmatter content (`matter()` deals with that for us)
        const { data: frontmatter } = matter(fileContent);
        // we get the post file name to use as the slug for our link
        const postName = path.basename(file, ".md");
        // we return two properties (`title` and `link`) that we've already seen inside `home.ejs` inside the `forEach` loop
        return {
          title: frontmatter.title || postName,
          link: `/${postName}`,
        };
      });

    // we render the `home.ejs` file and pass the property `posts` (that we run through the `forEach` loop
    res.render("home", { posts });
  });
});

Now run node main.js in your terminal and visit localhost:3000. You should see your / route populated with links to the markdown files that you created! 💃

There's a lot to digest there so, please, try every code line by yourself and see if it makes sense. Try to do different stuff, actually! Get the summary for your posts and find a way of displaying it inside the home.ejs file. Go crazy with it! Attach image urls and also try to display them. PLAY WITH IT!

Now, for the /post itself:

// main.js
app.get("/:post", (req, res) => {
  // via the params of the request we get the post identifier (in this case the slug)
  const postName = req.params.post;
  // now instead of grabbing the `posts` folder, we make sure to grab a file that has the same `filename` of our route inside the `posts` folder
  const postPath = path.join(__dirname, "posts", `${postName}.md`);

  // we jump inside the file
  fs.readFile(postPath, "utf8", (err, data) => {
    // once again we check for any errors
    if (err) {
      return res.status(404).send("Post not found");
    }

    // we fetch the content of the post and its frontmatter
    const { content, data: frontmatter } = matter(data);
    // we use `marked` to render the `htmlContent` (very important if you have `code blocks`, links, and other interesting stuff
    const htmlContent = marked(content);

    // we tell to render the `post.ejs` file and pass two properties, `content` and `frontmatter` that we'll pick and render inside our file 
    res.render("post", { content: htmlContent, frontmatter });
  });
});

Once again, run node main.js, and choose one of the links in the homepage. You should see your markdown file rendered as HTML!

As before, try stuff out; add elements to the markdown and see how they render; add new fields to the frontmatter and also get them to show.

You're now the proud owner of a blog made with Node! 💃

That's it

There's a lot more that we could do here but that's out of the scope, isn't it? We got something working, with what we intended to do, and that is perfect. Now it's your turn to ✨ make it shine ✨
See if you can change the head.ejs info by passing properties to it! Ideally, the tab name would change with the chosen content. And we should also have proper metadata when we share the website on social media so we also need that frontmatter info inside the head. Sounds like a good challenge, uh? 😎

As always, if you have any doubts, feel free to reach me via X.

An intro to Appwrite | Building a To-do list with SvelteKit

Rui Sousa — Sun, 07 Jan 2024 21:48:56 +0000

A to-do list is the playground for experimenting with a new technology, right? It ain't much but it allows you not only to understand the basics but also to get familiar with the docs for any extra 💫 dazzle 💫 that you may want to add.
And that's exactly what we'll do with Appwrite!

What is Appwrite?

Appwrite is an open-source BaaS (Backend as a Service), and it provides pretty much all the tools that you might need to get a backend up-and-running, such as Authentication, Databases, Functions and Storages; since there's no point in repeating what has already been said by others, please check this blog post to learn more about how Appwrite is structured and how it works.

Starting the project

We'll need, of course, to start a Svelte project so let's follow their walkthrough to do so.

npm create svelte@latest svelte-appwrite-todo-app
cd svelte-appwrite-todo-app
npm install
npm run dev

Just make sure to select the Skeleton option since we don't need the Demo code for what we're doing.

Once you have the project running, let's now initialize a project on Appwrite. We can also follow their guide for that; just make sure to stop before step 5 since we don't need to get into the Login page setup.

Appwrite structure and config

Alright, we should now have a base project to start working on and we're ready to extend it. We'll start on Appwrite's side!
Head over to your Appwrite console and select your project in there. Head over to Databases and you'll see an empty table.

Let's create a new database (name it whatever you want but I'll call mine Todos). After that, you'll be sent to a new screen for the Collections; if you followed Appwrite's blog post, you'll know that Collections are groups of Documents - for our app this means that todos (notice that it's all lowercase, different from the Todos database name) is our collection and each document will be a todo.

Create your collection and you should see a new screen for the documents (currently empty) inside that said collection.

Now, you won't be able to create any document because we need to define the properties (or attributes, in the Appwrite's console) that will compose each document. We'll create 3 different attributes: title, description and isCompleted. title and description will be strings and isCompleted will be of type boolean, and the 3 will be set as required - just follow the different prompts that Appwrite provides for creating an attribute but make sure that the types match the tutorial.

Now we're ready to start creating documents and we'll do that from our codebase, of course! 💃

Connecting our created database to the code

We'll be working with databases' ids and different info that should be secured so I would advise you to create a .env file to store said info. We'll do this by installing dotenv into our project and use it accordingly:

npm install dotenv --save

Now on the codebase, create a .env file and fill in the info for each variable that I show here (go back to the Appwrite guide if you get lost on where the ids are):

APPWRITE_PROJECT_ID=
APPWRITE_ENDPOINT=
APPWRITE_DATABASE_ID=
APPWRITE_COLLECTION_ID=

On our appwrite.ts file (or .js, as you wish, just remember to remove the types from your code if you're not using Typescript) we can now replace the hardcoded values for your variables:

import { Client } from 'appwrite';
import {
    APPWRITE_ENDPOINT,
    APPWRITE_PROJECT_ID,
    APPWRITE_DATABASE_ID,
    APPWRITE_COLLECTION_ID
} from '$env/static/private';

const client = new Client();

client.setEndpoint(APPWRITE_ENDPOINT).setProject(APPWRITE_PROJECT_ID);

export { client };

I've removed the Account definition because we won't need it (for this tutorial) and changed the exports a bit just due to preference.

Now, if you try to start a project, you'll be invited with a blank page with an error and if you look at your terminal you'll see AppwriteException: The current user is not authorized to perform the requested action. By default, Appwrite doesn't make assumptions about who can access which database or which collections so everything will be blank (aka, no one can access anything) so we need to solve this.

Head over to your collection and choose Settings. Scroll to Permissions and create a new role; for this tutorial we can start by selecting All guests and allowing for them to perform any action.

⚠️ For an actual app you wouldn't want to have this kind of role performing all kind of destructive actions but it works well enough for this tutorial.

Now, if you refresh your app in the browser, the error should have disappeared! Congrats, you've made your app extremely insecure (I'm just kidding! 😄)!

Finally, some actual code 😄

Now, our app will look incredibly boring but it will be plenty for this tutorial.
For starters, please copy & paste the following code into src/routes/+page.svelte for the initial look:

<script lang="ts">
</script>

<main class="column">
    <div class="todos-container box column">
        <h1>SvelteKit Appwrite To-do App</h1>
    </div>

    <form method="POST" action="?/create" class="box column">
        <div class="input-container column">
            <label for="title">Title</label>
            <input type="text" name="title" />
        </div>

        <div class="input-container column">
            <label for="description">Description</label>
            <input type="text" name="description" />
        </div>

        <button>Add Todo</button>
    </form>
</main>

<style>
    main {
        margin: 0 auto;

        max-width: 480px;

        font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
        color: #3e4850;

        gap: 1em;
    }

    .box {
        padding: 1em;

        border: 1px solid #ccc;
        border-radius: 8px;
        box-shadow: 0 0 8px rgba(75, 79, 91, 0.1);
    }

    .column {
        display: flex;
        flex-direction: column;
    }

    .todos-container {
        gap: 1em;
    }

    .todo-container {
        gap: 0.2em;
    }

    .todo-container:not(:last-of-type) {
        padding-bottom: 1em;

        border-bottom: 1px solid #ccc;
    }

    .title {
        font-weight: bold;
    }

    .description {
        font-size: 0.8rem;
        color: #717378;
    }

    h1 {
        margin: 0;

        font-size: 1.5rem;
    }

    p {
        margin: 0;
    }

    form {
        gap: 0.5em;
    }

    .input-container {
        gap: 0.5em;
    }

    label {
        font-size: 0.8rem;
        color: #717378;
    }

    input {
        padding: 0.5em;

        border: 1px solid #ccc;
        border-radius: 4px;
    }

    button {
        padding: 0.5em;

        border: 0px;
        border-radius: 4px;
        background-color: #151c29;

        color: white;

        cursor: pointer;
    }
</style>

We now have a foundation for our work and we're ready to make our first API call - getting the to-dos from our collection.

We'll start by going into our appwrite.ts file and create and export our function:

[...]

const getToDosFromDatabase = async () => {};

export { client, getToDosFromDatabase };

So, what do we need to do in our function? We need to get inside our database, pick the collection that has the to-dos and be able to grab all of them! Appwrite offers an excellent documentation and examples for all your needs so you shouln't have a problem doing so but let's go step-by-step.

To work with Appwrite databases, their API offers a Database class that has the necessary methods, so we can start by adding it to our appwrite.ts

[...]
const databases = new Databases(client);
[...]

Now, if you look at their documentation you'll find the listDocuments method, which is exactly what we need. It takes our APPWRITE_DATABASE_ID and APPWRITE_COLLECTION_ID and an additional optional argument to provide extra context to our query to filter it out; for us, the two required arguments are more than enough and our getToDosFromDatabase will look like this:

const getToDosFromDatabase = async () => {
    const { documents } = await databases.listDocuments(APPWRITE_DATABASE_ID, APPWRITE_COLLECTION_ID);
    return documents;
};

I'm solely getting the documents from the response because I don't really have a need for the full object that comes as a result, which provides a total and the documents!
With that, our appwrite.ts will now look like the following:

import { Client, Databases, ID } from 'appwrite';
import {
    APPWRITE_ENDPOINT,
    APPWRITE_PROJECT_ID,
    APPWRITE_DATABASE_ID,
    APPWRITE_COLLECTION_ID
} from '$env/static/private';

const client = new Client();
const databases = new Databases(client);

client.setEndpoint(APPWRITE_ENDPOINT).setProject(APPWRITE_PROJECT_ID);

const getToDosFromDatabase = async () => {
    const { documents } = await databases.listDocuments(APPWRITE_DATABASE_ID, APPWRITE_COLLECTION_ID);
    return documents;
};

export { client, getToDosFromDatabase };

Alright, so, where do we plug this getToDosFromDatabase? Svelte has a couple of ways of loading data, but, to cut it short, we'll use a +page.server.ts; my reasoning is that we're dealing with the ids of our project, database, and collection and that's not really something that we really want to expose to the user. Also, we're gonna have some form actions and we need a .server.ts file anyway!

So, on the same level as our +page.svelte we create a +page.server.ts and in it we can have a load() function where we call our getToDosFromDatabase, like so:

import { getToDosFromDatabase } from '$lib/appwrite';

export async function load() {
    const todos = await getToDosFromDatabase();

    if (todos) {
        return {
            todos: todos
        };
    }
}

We're now able to get the data from the return via the data property on our route and we can render stuff accordingly:

<script lang="ts">
    export let data;
</script>

<main class="column">
    <div class="todos-container box column">
        <h1>SvelteKit Appwrite To-do App</h1>

        {#if data.todos && data.todos.length > 0}
            {#each data.todos as todo}
                <div class="todo-container column">
                    <p class="title">{todo.title}</p>
                    <p class="description">{todo.description}</p>
                </div>
            {/each}
        {:else}
            <p class="empty-message">
        There are no To-dos. Create your first one!
      </p>
        {/if}
    </div>

    <form method="POST" action="?/create" class="box column">
    [...]
    </form>
</main>

<style>[...]</style>

So, if there's data and there are todos in data, we render each of them; if there's not, we just display a message saying so. At this point you should be able to see the empty-message paragraph, so, that's a good guiding star!

Let's mutate stuff, shall we?

Ok, we can now connect to our database and get the non-existent documents in our collection, but we want to actually place stuff there and doing that via the Appwrite dashboard is not very mega frontend dev of us, so let's fix that!

The Databases() class also provides a createDocument() method, and by identifying our database and our collection ids, we can use it! On our appwrite.ts we add the following:

[...]

const createTodo = async (title: string, description: string) => {
    const result = await databases.createDocument(
        APPWRITE_DATABASE_ID,
        APPWRITE_COLLECTION_ID,
        ID.unique(),
        {
            title,
            description,
            isCompleted: false
        }
    );

    return result;
};

export { client, getToDosFromDatabase, createTodo };

So, should be obvious on what's happening here but let's summarize it: createTodo takes a title and a description argument and we create an object (aka, a document entry on our collection) with the expected structure: title, description, and the isCompleted property that should start as false.

So, to connect stuff up... I've already added the form with its action on our +page.svelte code so stuff there is done, and, like I mentioned before, it's going to be on the +page.server.ts that we'll work with the form actions.

Looking at our form element you'll see that the expected action is create so we can start by that:

[...]

export const actions = {
    create: async ({ request }) => {}
};

Now we need to get the title and description and send them as arguments on our createTodo; with Svelte and its actions, it is expected that you access the form info via the request property.

import { getToDosFromDatabase, createTodo } from '$lib/appwrite';

[...]

export const actions = {
    create: async ({ request }) => {
        const data = await request.formData();

        const title = data.get('title') as string;
        const description = data.get('description') as string;

        if (!title || !description) {
            return {
                status: 400,
                body: {
                    message: 'Title and description are required'
                }
            };
        }

        const result = await createTodo(title, description);

        return {
            status: 200,
            body: result
        };
    }
};

Try your form now, I'll wait! ... ... ... Pretty cool, uh? 😜

Where to go next?

This post is already pretty long so I'm cutting it short right here; I might do a part 2 for the isCompleted attribut and for the authentication (remember the permissions? Yeah, we definitely don't want to release an app with that) but I would like to offer you the challenge of figuring it out for yourself.
You can find the full code here.

The challenge

We're missing a way to set a to-do as complete but we already have a isCompleted attribute. Look into Appwrite's documentation to figure out if there's a way of updating a document; once you have the method, create a function for it on the appwrite.ts and then find a way to connect it to the to-do that you want to mark!
Due to the way we set our permissions, anyone can change the to-dos and add more to the list and that's a huge problem! This is a much bigger challenge but, ideally, there would be a way to authenticate a user and we would change the permissions on our collection to allow just users (or maybe even just a specific role) to update the to-dos.

Are you up to the challenge? 😉 I promise you won't regret it if you follow it through!

And that's it!

Hopefully I've spiked your interest for Appwrite with this post and you're now eager to add a new tool to your belt! 💃
As always, if you have any doubts, feel free to reach me via X

Build a Quote Generator with JavaScript: Your first API project

Rui Sousa — Wed, 02 Mar 2022 19:13:14 +0000

If you’ve never worked with an API (Application Programming Interface) before, WELCOME! I assure you that this is going to be an excellent first time! 😄

The purpose of this tutorial is simple: to allow you to work with an API by making a single request and display its info on the screen. That’s it! No tricks! And we’ll probably do it in like 10 lines of JavaScript 🤘 How exciting is that?

So, to summarize, in this tutorial you’ll learn a bunch of stuff like:

selecting elements on the DOM
onClick events
trigger a fetch for an API
displaying info in empty elements

If you're really just interested on the code, here's a link to the CodePen with it.

What’s an API?

We should clarify on what’s an API if that’s something new to you.

An API is an intermediary that allows for two applications to talk between them, and it will have a set of functions that allow applications to access data and interact with external software components, operating systems, or services.

The most widely practical example to describe an API is the following: think of a waiter at a restaurant. When you (application 1) get at a restaurant, you place your order (request) with the waiter (API) and he tells the kitchen (application 2); the kitchen then makes your order, gives it to the waiter and the waiter gives it to you (response).

In our tutorial we’ll use an API that fetches data from a server and we’ll use the Fetch API to facilitate that communication (that means that we’ll actually be using two APIs in this tutorial 😦).

That’s enough theory for now but if you do have any doubts, please message me on Twitter.

Starting with the HTML

Every web app needs its HTML and ours is no different! Our HTML for this application is incredibly straight forward and all you need is a button and a div with an id. So your HTML will look something like this:

<button onclick='getQuote()'>Get quote</button>
<div id='insertQuoteHere' />

That’s it, job done! We can now move to the interesting part! 😄

The JavaScript

Most of the APIs require you to deal with secrets but that’s out of the scope of this tutorial so we’ll be using a completely free one called kanye.rest (I know, I know 😅).

Get our `div`

So, the first thing that we’ll need to do is to get our <div id='insertQuoteHere' /> because we need it readily availably to insert our quote into it. For that we’ll use getElementById() (if you don’t know what that is, it’s a method that will an object that represents the element with the id that we pass as parameter.

So, in this case, this is going to be our first line of JavaScript.

const divWithQuote = document.getElementById("insertQuoteHere");

Create our function

We need to create our getQuote() function and this function will do the request and print the data into our divWithQuote.

You’ll see me using an arrow function but you can use a regular function expression.

Let’s declare our empty function

const getQuote = () => {}

The request

Now that we have our function, we’ll run the fetch() function provided by the Fetch API, which will fetch (well, duh!) our data.

const getQuote = () => {
    fetch("https://api.kanye.rest")
}

If you know click on the button, you won’t see anything happening, BUT... Congratulations, you just made your first request! 🎉

Now let’s deal with its data! 😄

The basic format for any fetch request is as follows:

fetch('API_URL')
  .then(response => response.json())
  .then(data => console.log(data));

Now, some stuff here may look weird so let’s go through them:

The then() method will wait for a response from the request and execute whatever is inside it
Our response will look like an HTTP response, which means that, we need to extract the content from it and that’s why we use the json() method
After that extraction is complete, we can then deal with the parsed data and actual make something with it

With this settled, we can now adapt this format to our code and it will look like this:

const getQuote = () => {
    fetch("https://api.kanye.rest")
        .then(response => response.json())
      .then(data => console.log(data));
}

If you know click the button and open your console you should see the data, which will look something like this:

{
    "quote": "Life is the ultimate gift"
}

I want to take this opportunity to say how important it is to be curious about anything that you do with code.

LOG EVERYTHING! LEARN WHAT YOU’RE WORKING WITH! PLAY WITH IT!

Code might be confusing and scary but the best way of dealing with that it to play with it and get to know it so don’t be afraid to throw random console.log() around! 😄

From data to HTML

We’ve basically done everything that we need for our application to work. All we’re missing is to get that quote into our HTML and to do that we’ll use innerHTML.

While logging our data we can see that there’s an object inside with a single property (quote) so we can reference it by doing data.quote and we’ll get its value by doing so! This means that we can do the same for our innerHTML, like so:

divWithQuote.innerHTML = data.quote;

So our JavaScript will look like this in it’s entirety:

const divWithQuote = document.getElementById("insertQuoteHere");

const getQuote = () => {
    fetch("https://api.kanye.rest")
        .then(response => response.json())
      .then(data => ( divWithQuote.innerHTML = data.quote ));
}

If you know press the button you should see a quote appearing on your div! 🎉 Here’s the working code 👇
CodePen

And that’s it!

You’ve successfully created a quote generator! Well done! 😄

Hopefully you’ve learn how to work with APIs and you’re know able to dive deeper into how they work and what’s possible to do with them. 💪

Let me know what you thought about this post and feel free to follow me on Twitter 🤘

Create your own SvelteKit Blog with this starter

Rui Sousa — Mon, 17 Jan 2022 20:24:38 +0000

I was curious to see how SvelteKit behaved as the foundation for a blog, and, with my work, it was obvious to me that I should share this starter since it might help someone / inspire someone to experiment with Svelte!

With this starter, you get the barebones for you to create your own blog website using Svelte and Markdown! 🎉

Here's the starter link 👉 https://github.com/ItzaMi/sveltekit-markdown-blog-starter

If you have any doubts, please reach out here in the comments or send me a DM to my Twitter 😄

'Ship it then quit it' syndrome

Rui Sousa — Tue, 04 Jan 2022 20:10:23 +0000

In 2021 I built and tried to launch two projects: Noting and BeautifulCSS.
Although BeautifulCSS had its (small) success when I launched it, it soon ended. And all because I never learned how to properly maintain projects...

The dilemma

Anyone that is involved in some sort of developer’s community has heard about ‘shipping their projects’. This isn’t exactly a bad way of thinking since throwing your projects out there allows you to get feedback and improve them. But... What happens after you launch a project?

Honestly? Not much. It's just there.

And that's the issue!

While we often hear that's is great to ship your project early, no one explains what you should do next.

No one tells you how you should have a roadmap or have a marketing strategy! No one tells you how you should probably have started talking about your project like 2 years ago! And no one tells you how you should start building an audience way before launching a project!

If you don't do any of the things that I mentioned above, your project will most likely not stand the test of time.

What I've learned

I've learned, this year, that building your project with love isn't enough. It seems that that's the last thing that is needed to ship a project. Crazy, uh?
Your project needs, more than attention, intentionality. You need to sell it! Advertise it! Talk about it almost daily! Build the proper hype around it!

Now I know better. I've learned with it. I guess that's also a benefit of shipping early: it allows you to learn from your mistakes and I most certainly learned with mine.

I learned that I need to take a step back before building something that I want to release to the world.

Most importantly, I learned that I need to plan them rigorously. If I don't do it, I'll end up with a single goal for them, ship them and wait for the feedback, and that doesn't allow me to build on top of what I launch. With that single goal, I'll end up being reactive and, I feel like that's no way of building any type of project! At least not one that you learned to love!

What I'll do in the future

First things first, I need to engage with the community! Build connections, make friends, grow along with other people, learn with people that failed and with people that had immense success!
After that, I'll start creating a clear roadmap for my projects. Not just a development roadmap. A product roadmap! Something that allows me to build consistently, share it with the world and, ultimately, build enough interest around it (my two big inspirations for this are Tony Dinh and Jim Raptis - honestly, they are wild; it's amazing to see them build in public!).

And that's it!

The title of this blog post ended up being a bit dramatic ('Ship it then quit it' syndrome - drama much?) but I think it fully represents this behavior. It's something that inherently happens (at least for me) if you don't live (again, is this dramatic?) with intention. Hopefully, this post will serve as a stepping stone for 2022!

Let me know what you thought about this post and feel free to follow me on Twitter 🤘

How to add a Google Font to your Gatsby + Tailwind project

Rui Sousa — Wed, 13 Oct 2021 07:41:18 +0000

While I was building the first version of itzami.com, I found myself having a hard time finding out on the internet how I could import a Google Font into my website that was using GatsbyJS and TailwindCSS. (and the tutorials I found all told me to install a dependency). With some trial and error I was finally able to achieve it and with this blog post I hope to make the job a lot easier for everybody that tries to do the same! It's incredibly easy to do it but since I haven't seen anyone mention it so clearly, why not do it myself?

First step: Grab your font!

You probably already know how to do this but let's do a refresh on it: to get a font (or font-family) from Google Fonts you must first go into the website (duh!) and choose your prefered font (I know, this tutorial is like, super high-level!). Let's pretend it's Festive.
Within your chosen font, there are a lot of styles but for this blog post I'll just pick Regular 400. Tick the Select this style and a sidebar should appear. We won't use the the <link> but we will use the @import so you should see something like this:

@import url('https://fonts.googleapis.com/css2?family=Festive&display=swap');

This is all you need from Google Fonts!

Second step: Paste it on `index.css`

I recommend that you follow Gatsby's tutorial on how to install Tailwind on a project since it will give you all the initial files that you need.
Once you finish your setup your index.css will look like this:

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

Now, on this exact file, we'll add our recently acquired @import so your index.css should now look like:

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

@import url('https://fonts.googleapis.com/css2?family=Festive&display=swap');

This is the setup on index.css!

Third step: Extend your `fontFamily`

Now that you're correctly importing your new font, you need to be able to use it on your code via className so you must add it customize your Tailwind configuration. To do this we'll simply extend our fontFamily to include this new font and we'll do it on our tailwind.config.js. This means that your file will have following structure inside extend (among other stuff that you might have added):

module.exports = {
  purge: [],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {
      fontFamily: {
        festive: ["'Festive', cursive"],
      },
    },
  },
  variants: {
    extend: {},
  },
  plugins: [],
};

Be sure to copy the exact string that you find on your Google font page on the CSS rules to specify families section. Our festive here is what we type when we want to style any text with this new font.

You're done, baby!

Now you can freely use your new Google Font wherever you want by adding a new class that looks like font-festive! So, to style, let's say, an <h1>, you would do something like:

<h1 className="font-festive">Hello there!</h1>

Now make it appear everywhere!

Now that we know how to add a font to any element, it's also time to add this font to our entire app. To do so, we just need to style our body on our index.css:

body {
  font-family: 'Festive', cursive;
}

And now your entire app will appear with the new font and you don't really need to declare it on any element! Isn't that cool?

Wrap up!

And that's it! Now you can freely add a Google Font to your GatsbyJS + TailwindCSS project with no issue whatsoever!
Let me know what you thought about this post and feel free to follow me on Twitter 🤘

Announcing 'Beautiful CSS'

Rui Sousa — Tue, 28 Sep 2021 08:37:41 +0000

This week I launched a tool, Beautiful CSS.

You just have to click on any of the components and it will copy its style to your clipboard so you can use it freely!

I intend to increase its library so that it becomes the ultimate front-end developer tool!

It's also on ProductHunt if you want to upvote it 👉 https://www.producthunt.com/posts/beautiful-css

Any feedback is very much appreciated! 🤘

How to build an accordion with JavaScript

Rui Sousa — Thu, 03 Jun 2021 17:55:22 +0000

I've seen some people battle with accordions in the past and, well, it wasn't pretty. BUT... It's completely understandable! An accordion has a whole lot going on and on a first sight it seems like all the functionalities will be pretty hard to develop.

Well... I'm here to prove that that is wrong and I want to help you build your very best JavaScript accordion 😄 And in this tutorial you'll learn a bunch of stuff like:

selecting elements on the DOM
forEach loops
event listeners
toggling class lists

If you're really just interested on the code, here's a link to the CodePen with it. I also have a YouTube video for it if you're more of a visual person 👇

So, with all of that out of the way, let's start this post 😎

Starting with the HTML

We'll start by create a basic structure of the HTML. And here it's pretty straight forward. You'll want a wrapping <div> that will hold your accordion component and inside it you'll have different accordion items. Inside each item you'll want to have two things:

the content that will always show (it can be just a <p> or it can be an entire <div>)
a <div> that will have the content that will collapse (AKA, that will appear and disappear when you press 1)).

A made a image to illustrate the basic structure and I advise you, specially when you're starting, to sketch out what you're intending to build since it makes it easier to split everything into smaller parts so you can work on them separately.

So, now that we have our structure, we can build it. In my example below, as you can see I have the mentioned <div> that has everything inside and that's our accordion component and inside each I have an accordionTitle, which represents the content that will always be showing, and a accordionContent that will be the content that will appear and disappear. You can change up the HTML elements that you use (maybe you would prefer to use <ul> and <li>) but that's on you! And that's our HTML 🎉

<body>
  <h1>Accordion</h1>

  <div>
    <div class="accordionItem">
      <h2 class="accordionTitle">Tab 1</h2>
      <div class="accordionContent">
        <p>Information here</p>
      </div>
    </div>

    <div class="accordionItem">
      <h2 class="accordionTitle">Tab 2</h2>
      <div class="accordionContent">
        <p>Information here</p>
      </div>
    </div>

    <div class="accordionItem">
      <h2 class="accordionTitle">Tab 3</h2>
      <div class="accordionContent">
        <p>Information here</p>
      </div>
    </div>
  </div>
</body>

A step further with our CSS

We have our HTML up and that's great but that's not an accordion. We have at least to hide accordionContent to at least make it look like one so that's what we're going to do. We simply want to hide that content on this step so what we're going to add to our CSS is the following.

body {
  margin-left: auto;
  margin-right: auto;
  max-width: 40em;
}

.accordionTitle {
  cursor: pointer;
  -moz-user-select: none;
  -webkit-user-select: none;
  -ms-user-select: none;
  user-select: none;
}

.accordionTitle + .accordionContent {
  display: none;
}

The styling for the body and .accordionTitle it's just a matter of preference. I noticed, when clicking on .accordionTitle that I was getting highlighted text and I didn't wanted that so I chose to remove it with user-select and since I wanted for the user to know that this element was clickable, I changed the cursor that appears when you over it to a pointer. That's it.

The .accordionTitle + .accordionContent is what matters and, honestly, the adjacent sibling combinator is pretty much all you want here. It will style your .accordionContent based on if it immediately follows .accordionTitle and, on for my accordion structure, it's just what I need.

For now, this is the CSS that we'll need. We'll make some changes to it once we start working on our JavaScript but we'll get there right away!

It's alive... With JavaScript (and some CSS)

So, we've hidden our content but now we want to show it when we click on accordionTitle (or show it if it's showing, of course). So we want to grab this accordionTitle class and add an event listener to it, in this case a click event, and then some magic will end happening!

So, on our JavaScript we'll grab all the elements on our HTMl that have this .accordionTitle and we'll do it with querySelectorAll().

const accordionTitles = document.querySelectorAll(".accordionTitle")

This piece of codes grabs all the elements that have this class name and returns a NodeList. A NodeList is an object that has a collection of nodes in it which, in this case, it's our elements that have the .accordionTitle in them, which means, our <h2>.

Now that we have our elements, we need to add to each of them a click event and for that we'll use a forEach loop.

A forEach loop allows us to go through each element of an array (or, in this case, the NodeList) and do something to it. It's very similar to a .map() but, unlike .map(), it will not return anything from it because any return inside a forEach will be discarded. I'm using the forEach because I want to use the original data from my array/nodeList and do something with it instead of changing it.

So, we'll do something like the following.

accordionTitles.forEach(accordionTitle => {})

Now, inside these brackets we can define what we're doing with each item, our accordionTitle, and we know that we want for something to happen when we click on them so we'll add an eventListener to them.

accordionTitles.forEach(accordionTitle => {
  accordionTitle.addEventListener("click", () => {})
})

Here's we saying that, when we click on an accordionTitle something will happen and we'll define what happens inside these new brackets.

So... We know that now our div with the content is hidden and we want to show it so... how can we do that? Here's my approach to it:

On our CSS we're currently hiding the content based on our .accordionTitle element and I want to keep that logic to show it as well. Which means that I want to alter our .accordionTitle in some way that it allow for our .accordionContent to have a different styling (throwback to the adjacent sibling combinator).

On the JavaScript we'll change the classList of our accordionTitle by adding (or removing) a new class called is-open.

accordionTitles.forEach(accordionTitle => {
  accordionTitle.addEventListener("click", () => {
    accordionTitle.classList.toggle("is-open")
  })
})

So, what's my way of thinking here?
If I can add a class to my accordionTitle, and I'm controlling this accordion content with that same element on my CSS, I can add a new CSS rule which tells my code that, when the .accordionTitle also has the class is-open, then the .accordionContent that comes immediately after it should have a display: block and it looks like this.

.accordionTitle.is-open + .accordionContent {
  display: block;
}

So, once again, I'm controlling .accordionContent visibility, or presence, with .accordionTitle and by toggling a new class to .accordionTitle, I'm able to show and hide .accordionContent as I wish.

And now, it just works, if you would try it. And you have a fully functioning accordion with very few lines of JavaScript, two classes in the HTML and pretty much just two CSS rules. Isn't that amazing? 🤯

Let's go even further

Currently our code allows us to open and close any tab but all the others that might be open stay like that and that's not really the perfect accordion so let's work on it, shall we?
Currently we're toggling each element independently but that's not what we want. We want to check if there are already any element that are open already and we want to remove that property so this is what I'm going to do:

I'll start by removing our toggle and first I want to create an if/else statement. On my if I want to check if the accordionTitle has the class is-open and, if it does, I want to remove it. We'll do the following on our JavaScript

if (accordionTitle.classList.contains("is-open")) { accordionTitle.classList.remove("is-open") }

Now, my else will be responsible for adding the is-open class and we can do it like this

else { accordionTitle.classList.add("is-open"); }

At this point we're basically at the same level that we were with the toggle. Now, on this else statement I want to see if there are any other elements with the .is-open class and, if there are, I want to remove it and we can do it like this.

First we do a querySelectorAll for all the elements with the .is-open class like this

const accordionTitlesWithIsOpen = document.querySelectorAll(".is-open")

Then we'll need to run a new forEach loop to iterate over each element so we can remove the class and that looks something like this

accordionTitlesWithIsOpen.forEach(accordionTitleWithIsOpen => { accordionTitleWithIsOpen.classList.remove("is-open") })

And we're done! Now once you click on a tab the other will close and we have a fully functioning accordion! 🎉🕺
Here's the working code 👇

Here's a challenge for you

I would like to challenge you to do something now: using what you've learned so far, I would like for you to create a button that would close and open all the tabs. Are you up for the challenge? If you are, send me your code to my Twitter 😄

And that's it!

Hopefully, you learned everything you need to know about building your own JavaScript Accordion and you understood that it's not that hard to make something that rocks 💪
Let me know what you thought about this post and feel free to follow me on Twitter 🤘

Creating an Accordion | HTML, CSS, JavaScript | Tutorial

Rui Sousa — Sun, 25 Apr 2021 19:52:37 +0000

In this tutorial I show you, step by step, how can build a fully functioning accordion using HTML, CSS, and JavaScript.

It's the perfect tutorial for any beginner since I'll show my thought process and we'll end up with a functioning accordion that opens one tab at a time!

Check out the video here

Boost your CSS animations with Intersection Observer API

Rui Sousa — Sun, 07 Feb 2021 13:15:47 +0000

CSS animations can be a pain in the 🍑, and what's even worst is to trigger them at the exact moment. For that exact reason, and if I may be perfectly honest with you, I opt for not using them most of the time. However...

Presenting: Intersection Observer API

Before starting, if you need a refresher on what's an API, this is a good place to get info on it

You may think that I'm out of my mind for suggesting that you should use an API for animating CSS but hear me out... GitHub uses it to make their homepage more performant and faster so you know it must be good!

When we usually want to check an element's position in the window we might end up using stuff like elem.clientTop, elem.offsetTop or even elem.getBoundingClientRect() but the truth is that these properties/methods will trigger the browser to calculate the required style and layout (check the whole list of properties that target this and a further explanation here) which creates a performance bottleneck.

A way to circumvent this is by using the Intersection Observer API, which, according to the MDN documentation, 'provides a way to asynchronously observe changes in the intersection of a target element with an ancestor element or with a top-level document's viewport.'. So, basically, we'll just monitor if an element will enter/exit another element/the viewport and that's way easier for the browser to process.

So... How do you do it?

The IntersectionObserver interface can be created very easily and all you have to do is to pass a callback to it and some options. The callback is what decides what will happen to the list of IntersectionObserverEntry objects and the options allow you to control the circumstances in which the callback will be called (please refer to the MDN documentation for full details on this).

For example purposes only, we'll not define our options (which will make them adopt some default values) and we'll simply work with our callback, so our initial setup would be something like this:

let expansionObserver = new IntersectionObserver((entries) => {
  entries.forEach((entry) => {
    if (entry.intersectionRatio > 0) {
        // something here
    } else {
        // something here
    }
  });
});

Now that we have our expansionObserver, we need to grab the elements that we want to animate. For this we'll use document.querySelectorAll() and we'll get all the elements with the class .expand.

So, on our HTML it would look like this:

<body>
    <div id="section-one"></div>
    <div id="section-two">
      <div id="container">
        <h1 class="expand">Hello</h1>
      </div>
    </div>
</body>

And our JavaScript would look like this:

const elementsToExpand = document.querySelectorAll(".expand");

After this, we need to tell the IntersectionObserver that we want to observe these elements, and since we're using querySelectorAll() we need to loop over elementsToExpand and we'll use a forEach() for it.

elementsToExpand.forEach((element) => {
  expansionObserver.observe(element);
});

To finish our JavaScript part, we need to fill the if/else statement we wrote on our callback. Here we'll want to style our elementsToExpand with the animation that they should have like so:

let expansionObserver = new IntersectionObserver((entries) => {
  entries.forEach((entry) => {
    if (entry.intersectionRatio > 0) {
      entry.target.style.animation = `expansion 2s ease-in-out`;
    } else {
      entry.target.style.animation = "none";
    }
  });
});

So, this is the whole behaviour that you have to recreate and now all we have to do is to define in our CSS this expansion animation:

@keyframes expansion {
  from {
    transform: scaleY(0.1);
  }
  to {
    transform: scaleY(1);
  }
}

And we're done! You can now check the full example preview and play around with it on CodeSandbox! I've added an extra element with a different animation so you could get a full grip of what's happening! 😄

And that's it!

What did you think about the Intersection Observer API? Will you give it a try on your next project?
Let me know what you thought about this post and feel free to follow me on Twitter 🤘

I built a note-taking app with markdown and local storage using ReactJS

Rui Sousa — Wed, 13 Jan 2021 19:58:06 +0000

There are tons of note taking apps out there but I wanted to build mine to see how hard it actually was and during the holidays I did it!

Take a look at it here

So, Noting is built with ReactJS, TailwindCSS and uses @uiw/react-md-editor as the Markdown editor. It also has local storage. And has dark mode, because Tailwind really makes that easy

It's a very simple app but I do believe it covers everything I wanted it to have so I'm incredibly happy for it!

There's absolutely no reason for me to brand this project with an actual name, cover and what not but I got into the mentality of "It's a real product and I really need to finish it" and it kept me accountable!

If you have any doubts or suggestions, please comment them here!

Also, I enjoy building in public so, if you're interested, you can follow me on Twitter!

How I use Notion as a developer

Rui Sousa — Tue, 08 Dec 2020 09:57:22 +0000

Notion is an amazing tool that helps you organize your work and you can pretty much adjust to all of your needs. Also, there are a lot of templates to choose from made by incredibly creative people.

My Overall Setup

I use Notion for a lot of stuff (activity tracker, money manager, diary) but it all started when I realized that I had way too many development blog posts saved in my browser's bookmarks. Once I took a clear look at them I said to myself

There's no way I would ever find here, even if I wanted

So, something had to be done about it and that's when I started using Notion! My first database was Reading List.

Reading List

The Reading List serves as my organized collection where I put the articles or tutorials that I find interesting for stuff that will surely be useful for my career. More than being a collection of stuff that I haven't read before, it's a collection of stuff that I know will always be useful for me and that I should always take into consideration.

Yes, a Google search might serve the same purpose but here I'm capable to organize the info as I want

And that's what I do. Since Notion allows you to add tags and filters, it's the perfect way to only what you actually want to see, which facilitates search. I also ended up using Gallery mode because, for me, having a list of links isn't particularly interesting and I want something that is eye-popping and I can find easily. I would say that the images do the trick!

However, I ended up realizing that not everything belongs to the Reading List and they are just stuff that I find around the internet that seems interesting but I don't really have time to read them right when I find them so that's where Quick Links appear!

Quick Links

Quick Links pretty much represents what I don't want my Reading List to look like but when you're on your phone you don't have time to make an incredible-looking database. Instead, you just copy & paste the link and title and you're all set for when you actually have time to study whatever you've found.
It basically serves as a triage for whatever comes into my Notion. The material does the check-in here and then they are properly dropped in their own place! I try to have this page as clean as possible since I don't want to repeat my mistake with the bookmarks!

Task List

I don't like to program my day or even week but, sometimes, when you actually want to have side-projects, you need to organize your life! If you don't, you'll never find the time to work on them so that's why this Task List exists. I mostly use pen and paper for work but for my side projects, considering that I only have the weekends to work on them, it's a great tool and helps me assess the project's progression.

Blog

I think this one is self-descriptive but I write all my content on Notion before assessing if it's good enough to be published. It's also where I take note of topics that I might want to cover or links to other blog posts that I may want to expand upon.

Note Taking

Here stands the important notes that I take (well, duh!) from my Reading List or books. Some things aren't worth taking notes on and some others deserve a special place to which I can quickly refer to. For example, Rework and The Opinionated Guide to React are two books that I read, enjoyed, and took some notes along the way and I want to preserve them without having to get to the original material again!

App Ideas

I guess that we all have this section on a paper, note app on the phone, or a word document but here stands my quirky ideas for apps, including with technologies that I have no idea on how to work with. Some are supposed to be personal projects, others might turn into actual products. The important part for me here is that I classify these projects on their type (personal or product) and degree of execution ("As of now, how easily can I build it and how motivated am I to do so?"). For me, the degree of execution plays a huge part in it because while all ideas are great, I may just not feel incline to elaborate on them... but I don't want to lose them as well.

Learning X

This is basically a sub-division of Note Taking but I also insert here resources for these specific technologies. I'm still starting to build a system for this section but at least I have a visible section for something that I'm currently learning and that's the important part!

That's pretty much it!

If you read this far, thank you so much for it! Hopefully, this post ends up helping something that might need some organization in their life!
I usually ramble a lot on Twitter so you can find me there!

Forem: Rui Sousa

How to build a blog with NodeJS

Start that project!

Explaining the dependencies

Alright, back at it!

Time to template like you never templated before!

The partials

The views

The blog posts! 📄

Time to see some stuff on the screen!

That's it

An intro to Appwrite | Building a To-do list with SvelteKit

What is Appwrite?

Starting the project

Appwrite structure and config

Connecting our created database to the code

Finally, some actual code 😄

Let's mutate stuff, shall we?

Where to go next?

The challenge

And that's it!

Build a Quote Generator with JavaScript: Your first API project

What’s an API?

Starting with the HTML

The JavaScript

Get our div

Create our function

The request

From data to HTML

And that’s it!

Create your own SvelteKit Blog with this starter

'Ship it then quit it' syndrome

The dilemma

What I've learned

What I'll do in the future

And that's it!

How to add a Google Font to your Gatsby + Tailwind project

First step: Grab your font!

Second step: Paste it on index.css

Third step: Extend your fontFamily

You're done, baby!

Now make it appear everywhere!

Wrap up!

Announcing 'Beautiful CSS'

How to build an accordion with JavaScript

Starting with the HTML

A step further with our CSS

It's alive... With JavaScript (and some CSS)

Let's go even further

Here's a challenge for you

And that's it!

Creating an Accordion | HTML, CSS, JavaScript | Tutorial

Boost your CSS animations with Intersection Observer API

Presenting: Intersection Observer API

So... How do you do it?

And that's it!

I built a note-taking app with markdown and local storage using ReactJS

How I use Notion as a developer

My Overall Setup

Reading List

Quick Links

Task List

Blog

Note Taking

App Ideas

Learning X

That's pretty much it!

The `partials`

The `views`

Get our `div`

Second step: Paste it on `index.css`

Third step: Extend your `fontFamily`