DEV Community: Hossomi

Frontline: Running Something

Hossomi — Sat, 05 Nov 2022 21:01:25 +0000

Hello everyone! You have probably noticed by now that I am not a consistent writer. It is finally time to run and see something!

Today we will implement the most basic of all: a CRA client talking to an HTTP server to display something.

In this article | Repository | Changes | Final commit

Server

The server is the simplest piece: an Express HTTP server that returns Hello world on GET. We start by installing Express in the server workspace:

yarn workspace @tamiyo/server add express

Then we write the server in index.ts:

import express from 'express'

const app = express()

app.get('/api', (req, res) => {
    res.send("Hello world")
})

app.listen(8000, () => console.log("Listening at port 8000"))

The basics of Express is really simple and intuitive, so I probably don't need to explain the code above. To run, we can build and manually run the built script:

yarn tsc --build
yarn workspace @tamiyo/server node build/index.js

The first command will transpile Typescript into Javascript as we discussed in the last article. The second will run the transpiled Javascript file using Yarn's module resolution, required since we use workspaces.

We can test our server with curl:

$ curl http://localhost:8000/api
Hello world

Client

The client is a basic CRA application that we will modify to get a message to display from our server.

⚠️ First of all, we will disable Yarn's Plug'n'Play (PNP) resolution:
yarn set config nodeLinker node
yarn install
Although there are sources on the internet saying that it should, I could not make Workspaces + PNP + CRA work properly. I decided to not spend more time on that and focus on actual development.

We will replace our current client with code generated with CRA:

rm -r client
yarn create react-app client --template typescript

Our old client had some important configuration discussed in the last article. In package.json, the name was changed and type was removed. Put them back:

{
  "name": "@tamiyo/client", # <-- Change back
  "version": "0.1.0",
  "private": true,
  "type": "module", # <-- Put back
  [...]

In tsconfig.json, we extracted most of the properties to tsconfig.common.json. So we can revert it, keeping only the few additional properties:

{
  "extends": "../tsconfig.common.json",
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "build",
    # Additional properties:
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "noEmit": true,
    "jsx": "react-jsx"
  }
}

With that, you should be able to run the template and run it in your browser (CRA will open itself) by running the start script with Yarn:

yarn workspace @tamiyo/client start

Integrating

The last step for today is modifying our client to make a request to our server and display the response on screen. This request should be made by the App component:

function App() {
  const [text, setText] = useState("Loading...")
  useEffect(() => {
    fetch('/api')
      .then(res => res.text())
      .then(setText)
  }, [])

  return (
    <div className="App">
      // [...]
      <p>
        {text}
      </p>
      // [...]
    </div>
  )
}

This should be easy if you already know React hooks. Here is a quick explanation anyway:

We use useState to define a state variable text with initial value Loading.... setText should be used to update its value.
We use useEffect with an empty array in the second argument to run an effect only once when the component is mounted.
This effect makes the request using fetch, parses the response as text using and store it in the text state variable, triggering a component re-render since the state changed.
The actual component renders text on screen, which will now be Hello world.

However, if you start the server and open the client, you will see this:

This happens because the client is actually making the request to the CRA development server that is serving the client pages, and not our server! In production these two servers would be the same, but we are not there yet.

CRA provides a solution for this in development: proxying. We can easily enable this in client/package.json:

{
  "name": "@tamiyo/client",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "proxy": "http://localhost:8000", # <-- Proxy to here
  # [...]

With this, the CRA development server will proxy unknown requests (i.e. that are not requesting a client page) to our server that is running on port 8000. Restarting the client and trying again, you should finally see this:

The shared library

Remember we have a shared workspace, where we will place common code? Now is a good time to link it to both client and server. For starters, let's just define two variables in shared/index.ts:

export const GREETER = 'Hossomi'
export const GREETING = 'Hello world!'

GREETER will be used by the client and GREETING will be returned by the server. Since they are all Yarn workspaces and Yarn handles them as packages, we can install the shared library as any other package:

$ yarn workspace @tamiyo/server add @tamiyo/shared
$ yarn workspace @tamiyo/client add @tamiyo/shared

A small change in shared/package.json is also necessary so that Typescript can correctly find sources inside the shared library module:

{
  "name": "@tamiyo/shared",
  "version": "1.0.0",
  "packageManager": "yarn@3.2.0",
  "main": "build/index.js" # <-- Add this
}

We can now change our server's index.ts like this:

import { GREETING } from '@tamiyo/shared'

// [...]

app.get('/api', (req, res) => {
    res.send(GREETING)
})

And the client App.tsx like this:

import { GREETER } from '@tamiyo/shared'

// [...]

<p>
  {GREETER}: {text}
</p>

After rebuilding and restarting our applications, we can verify that both client and server are using the variables from the shared library:

Quality of life

Today, we had to run some quite verbose commands to start our client and server. To make our lives easier, we can put them in Yarn scripts in the parent package.json:

{
  "name": "tamiyo",
  "version": "1.0.0",
  # [...]
  "scripts": {
    "build": "yarn tsc --build --verbose",
    "clean": "yarn tsc --build --clean",
    "start:server": "yarn workspace @tamiyo/server start",
    "start:client": "yarn workspace @tamiyo/client start"
  },
  # [...]

We also need to define a start script in server/package.json:

{
  "name": "@tamiyo/server",
  # [...]
  "scripts": {
    "start": "yarn node build/index.js"
  },
  # [...]

We can now run yarn build to transpile Typescript, yarn start:server to start the server and yarn start:client to start the client, much shorter commands! CRA even has hot reload in development mode, so changing client code while it is running will automatically update in the browser. I will investigate how to do the same for the server.

Next step

We have a basic client-server application running, but we are using plain HTTP. In the next step, I will get started on GraphQL. It is a new world to me, so I am not sure an entire article will be needed. If it turns out simpler than I expect, I can also explore MTG JSON data sets.

Frontline: Preparing Grounds

Hossomi — Sun, 14 Aug 2022 05:14:41 +0000

Hello everyone! A long time after the first post, it's time to roll up the sleeves and start coding.

Before anything else, I like to prepare the project structure and build. The logical first step is installing Yarn and Typescript and get it to build anything.

In this article | Repository | Changes | Final commit

Setting up Yarn

To install Yarn, it is recommended to use Corepack, bundled with Node starting in 16.10. It seems to be an all-in-one package manager, and it already includes Yarn out of the box. All you need to do is run corepack enable (since it is experimental and disabled by default) and then yarn init -2 to initialize a new project.

ℹ -2 ensures that it uses Yarn 2+ (modern), required to work with zero-installs. More on it later!

As I mentioned, I want to use Yarn workspaces to organize modules. Each module needs its own package.json file, so let's start with the following structure:

📦tamiyo
 ┣ 📂client
 ┃ ┗ 📜package.json
 ┣ 📂server
 ┃ ┗ 📜package.json
 ┣ 📂shared
 ┃ ┗ 📜package.json
 ┗ 📜package.json

The package.json content is mostly the usual, the difference being that the parent file contains a workspaces field specifying where the workspaces are:

 {
  "name": "tamiyo",
  "version": "1.0.0",
  "packageManager": "yarn@3.2.0",
  "workspaces": [
    "server",
    "client",
    "shared"
  ]
}

For the modules, we are prefixing their package names with @tamiyo for consistency. The client file for example is like this:

{
  "name": "@tamiyo/client",
  "version": "1.0.0",
  "packageManager": "yarn@3.2.0"
}

Running yarn install makes sure we've setup correctly, and you'll notice it creates some files. The yarn.lock is well known, and the others are related to Yarn's zero-installs: .yarnrc.yml, .pnp.cjs and the .yarn directory. With all these checked into the repository, you no longer need to run this command unless dependencies change (hence zero installs)! Read the documentation for more advantages of this mechanism.

Setting up Typescript

Let's get started with Typescript! The first thing to do is to install it with yarn add -D typescript. It will install the tsc CLI tool that we can run with yarn tsc to compile Typescript code into Javascript, making it runnable in broswers, node and the like.

Typescript is organized in projects, indicated by a tsconfig.json file along with various project settings. It can also be divided into smaller subprojects, which pairs well with the Yarn workspaces we are using! We just have to place a tsconfig.json file in each workspace as well.

📦tamiyo
 ┣ 📂client
 ┃ ┣ 📜package.json
 ┃ ┗ 📜tsconfig.json
 ┣ 📂server
 ┃ ┣ 📜package.json
 ┃ ┗ 📜tsconfig.json
 ┣ 📂shared
 ┃ ┣ 📜package.json
 ┃ ┗ 📜tsconfig.json
 ┣ 📜package.json
 ┗ 📜tsconfig.json

The root tsconfig.json is special: it has a references property specifying the subprojects, which in our case are the workspaces. We also specify "include": [] so that the root project doesn't build anything, since it's not a module itself.

{
  "references": [
    { "path": "./shared" },
    { "path": "./client" },
    { "path": "./server" }
  ],
  "include": []
}

The workspaces are where actual code resides, so their tsconfig.json contains compiler options:

{
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "build",

    "target": "es6",
    "strict": true,
    "noFallthroughCasesInSwitch": true,
    "module": "commonjs",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "composite": true,
    "esModuleInterop": true,
    "isolatedModules": false,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true
  }
}

You can see their meaning in the TSConfig reference. It's important to note that composite: true is required when using Typescript subprojects. To avoid repeating all those properties in each workspace, we can extract them to a common tsconfig.common.json and make the workspaces extend them:

# ./tsconfig.common.json
{
  "compilerOptions": {
    "target": "es6",
    "strict": true,
    "noFallthroughCasesInSwitch": true,
    "module": "commonjs",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "composite": true,
    "esModuleInterop": true,
    "isolatedModules": false,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true
  }
}

# {module}/tsconfig.json
{
  "extends": "../tsconfig.common.json",
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "build"
  }
}

With that, we should be able to build from the root directory. Let's put a simple file under the src directory of each module to test it out:

// {module}/src/index.ts
console.log('Hello!')

Running yarn tsc --build --verbose should compile all the Typescript files and generate .d.ts and .js files under {module}/build directories, as we instructed in the configuration. These files are what will be actually run by either Node, browser and the like.

Next step

Our project can at least be compiled! Next, it is time to get something up and running. As I mentioned, I will use Create React App to build our client, providing us a quick lift. We'll also see how we can implement and integrate our server with it.

To the frontline!

Hossomi — Fri, 20 May 2022 04:14:27 +0000

Hello everyone! This is Hossomi, a Java backend developer trying to learn frontend. There probably is a multitude of people out there telling their own story of a similar journey, and mine is just one more of these. But anyway, sharing won't hurt, and someone might even enjoy!

In this series, I will try to build and deploy a full-stack web application using languages, libraries and technologies I'm not very familiar with. I won't go wild on complexity because it's more of an exercise than anything serious, but I will take this chance to learn as much as I can and share the experience along the way.

In this first post, I will introduce myself, my motivation and experiences. At the end, let's think a little about what to build!

💡 Motivation

I have been a backend developer for a few years now, and I am still very satisfied with it. Since I started my tech career, I have worked with various programming languages (mainly, but not only, Java), frameworks, tools, services and other technologies. There is always so much to learn and so many possibilities!

As one of those people who also code as a hobby, I have personal projects in which I have to deal with databases, web APIs, deployments and such. However, there is one aspect I was never able to even make a dent: GUI. Web applications running in a browser are popular nowadays, and only attainable with technologies that I have nearly zero knowledge.

This gap in my skillset feels very crippling! Any project, personal or not, that required frontend skills is usually out of my reach. So I decided it was time to fill that gap.

🥉 The bad experience

This is not going to be my first time learning frontend. A few years ago, I wanted to make an application to help my brother manage his Magic the Gathering collection.

I thought that a desktop application would be best, so looking around I came across Electron. I didn't know any JavaScript or any of its frameworks and libraries at the time, but this could be a good opportunity to learn, right? Well, I quickly found out the hard way that JavaScript ecosystem can be absurdly overwhelming.

Installing libraries and getting something on the screen is not difficult with a tutorial. But I had to go and overstep by a lot! Suddenly, I am learning JavaScript, React, Redux, Webpack, Babel and a bunch of other things that came along all at the same time. Eventually, I cloned a boilerplate repository with all these preconfigured, but it was so huge I couldn't even fathom.

I was able to get slightly off the ground, learn a little of each of those technologies and get some things working on the screen. At some point, though, I realized I was blindly changing code until it barely worked as I wanted. The lack of understanding of the fundamentals was increasingly unproductive and demotivating. The code was so entangled that trying to learn properly now was difficult. Maybe it was time to step back and start smaller.

🥈 The better experience

During the next few years, I had the chance to work with frontend again in my job in a much smaller scope. I learned about Create React App (CRA), an amazing tool for beginners that encapsulates many development aspects for a static web application. With CRA, I no longer had to worry about Webpack, for example, which is already a huge weight off my shoulders.

Along the way, I realized that I didn't need Redux. React's context API and hooks also came up to solve probably everything that I would use Redux for.

Of course, I will have to come back for all these tools (or alternatives) eventually. This new approach worked for the applications I was working on at the time and allowed me to focus on fewer things.

🥇 The next experience

Let's start with a very high level idea of what I will build and a few technologies to focus on.

I still want to help my brother with Magic the Gathering (MTG), so here's some background. When a new set is about to be released, some local stores hold pre-relase tournaments. The cards are published beforehand so players can study and prepare, and my brother builds a spreadsheet with lots of information for that.

I wrote a shell script that fetches the set data from MTG JSON and generate a CSV using jq with all the data he needs, which he then copies over his spreadsheet with his formulae and formatting. He can't run the script (not a programmer) so I run it and give him the CSV. What about turning that into a more flexible, self-served web application?

🎯 GOAL: display a set data from MTG JSON in a dynamic table and generate a CSV from it.

On the technical side, these are what I have in mind initially. Of course things can change along the way.

Typescript. I have tried it before, thinking that I would adapt easily coming from a statically typed main programming language, but I was wrong. I don't have demands pressuring me this time, so I believe I will be able to learn it properly now. I might not be too strict, though, it depends on how it goes.
GraphQL. MTG JSON has quite a lot of data for each set and card. A more flexible interface for querying those fields might be useful, and suitable use case to try GraphQL out at the API layer.

MTG JSON has a GraphQL API in beta available for supporters in case you are interested in such API (probably better than mine will be).

React (and CRA). I will stick to it since I still have much to learn. I will also have more time and freedom to study and experiment.
MUI Core. I have used previous versions of Material UI and enjoyed it. The new v5 seems slightly different, but I think it is worth learning to develop UI quicker with a system behind it.
Yarn. Workspaces sounds very nice for organization even though I won't be publishing packages out of the application. NPM is fine, I just think I can try something new here without shooting myself in the foot.
Heroku. The simplest application platform I know, yet very powerful. I have tested it a few times but never went too deep, I want to learn more about its capabilities.

There are other development aspects I haven't even thought about yet, I will come up with them along the way. This is enough to get us started!

🏁 Ready, set, go!

Keeping the MTG theme, I chose to name our application after the MTG character Tamiyo. She is a planeswalker that seeks and records knowledge throughout the multiverse. It somewhat fits the purpose of this application.

Check out the GitHub repository (at the time of this writing, empty) and stay tuned for next articles!