Forem: liwenzhi

Minimal dev.to post publish tool

liwenzhi — Thu, 18 Feb 2021 20:48:03 +0000

Just wrote a small NodeJS application to publish markdown content into dev.to:

For those devs who love to use VSCode to write blog articles, have a try this minimal dev.to blog publisher.

Any feedbacks are welcome!

I'm currently looking for a new job, if you like my open source projects, and my experience match your needs, feel free to contact me.

Thank you!

Using image in Gatsby application by a clear way

liwenzhi — Thu, 15 Aug 2019 20:31:23 +0000

Gatsby has many features to win the developers' love and prevails over other mainstream static site generators. One of those features is gatsby-image component. It solved the image optimization problem with the specified dimension scope you defined, progressively and responsively presenting to the webpage gives user a comfortable browsing experience.

Steps to use gatsby-image

Like the official doc said, there are three steps needed to implement a gatsby image in Gatsby website:

install gatsby-image component and two other build dependency plugins: gatsby-transformer-sharp and gatsby-plugin-sharp
define image source directory in gatsby-source-filesystem plugin as well as above two plugin in gatsby-config.js plugins section
import gatsby-image component to your gatsby page component and declare a image tag/instance with a fixed or fluid property whose value derived from graphql query.

In the step 2, you tell the Gatsby build tool, where to find the root directory of all the image files. Just like the doc example, the root directory here is src/images/ of current Gatsby project:

{
  resolve: `gatsby-source-filesystem`,
  options: {
    name: `images`,
    path: path.join(__dirname, `src`, `images`),
  },
},

In the step 3, you tell gatsby-image component instance where to get the file: graphql query result.

export const query = graphql`
  query {
    file(relativePath: { eq: "blog/avatars/kyle-mathews.jpeg" }) {
      childImageSharp {
        # Specify the image processing specifications right in the query.
        # Makes it trivial to update as your page's design changes.
        fixed(width: 125, height: 125) {
          ...GatsbyImageSharpFixed
        }
      }
    }
  }
`

Which directory to put image?

After seeing this graphql code snippet, you may wonder where's the blog/avatars/kyle-mathews.jpeg? Is it under project root or src/images? let's take a test from a blank gatsby project.

create gatsby project:

$ gatsby new using-image-in-gatsby

place kyle-mathews.jpeg image under src/images/blog/avatars/.

replace original index.js content with the following code:

Note: Dont forget the data property in IndexPage properties.

Now, we can start the website without the need to modify the other stuff:

$ gatsby develop

Visit the http://localhost:8000/ in your browser, you'll see the correct result.

This experiment verified our speculation, that is:

gatsy-image query(graphql) using relative path under the path defined in gatsby-source-filesystem as query condition!

How about the dynamic image source value?

Above example use static value blog/avatars/kyle-mathews.jpeg to query in graphql expression. Then, what if the query condition is from markdown file meta data?

Official doc about Working with image in Markdown posts and pages told us the placing the featuredImage in the same position of markdown file:

file structure:

├── src
  ├── pages
    ├── example-post.md
    ├── awesome-image.png

example-post.md:

---
title: My Amazing Post
featuredImage: ./awesome-image.png
---

Content goes here!

In this solution, it works though, but, if you have many posts which include many images in each post, the directory structure will grow big dramatically and end up with chaos.

How to restructure the images path in a reasonable way?

Step one: deine a new content source in gatsby-config.js

plugins: [
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        path: `${__dirname}/content`,
        name: `content`,
      },
    },
    ...
]

Step two: place all the images under content/assets

separate image files and .md files to different folder

├── content
  ├── posts
    ├── example-post.md
    ├── ....md
  ├── assets
      ├── fantastic-image.png
      ├── awesome-image.png
      |── ...
├── src

Step three: reference the image using relative path in markdown file metadata.

example-post.md:

---
title: My Amazing Post
featuredImage: ../assets/awesome-image.png
---

Business intro is missing...

How to use html img tag in a Gatsby application

In a normal web application, html img element can use relative or absolute path to assign src property. We use image in a native and static way like the official doc said, place image under static folder, display image in webpage as we expected. But, when we build and deploy the gatsby site the GitHub Pages, visit it under an URL pattern like this:

https://username.github.io/your-gatsby-website/

The images declared by img tag broken all!

Although all the gatsby-images built by $ gatsby build --prefx-paths works, but those native imgs don't work.

What's the solution?

One solution is refactor all the imgs to gatsby-image components
Another solution is add context prefix the img src property.

For example:

<img src="/ueofcweb/images/project-home.jpg" className="img-fluid" alt="ultronele screenshot" />

ueofcweb is the github project name, images/project-home.jpg is actually under ueofcweb/static.

If you're refactoring a traditional website which use a large amount of img tags, the second option would be a cheap option. My production officail site is migrated from bootstrap/jquey stack, while I was adding it to the Gatsby showcase, I spend hours to figure out that the second approach is the best way to me.

Last note I can give in this post is:

Do not include folders under static folder, it's a BAD practice ending up with build error `childImageSharp' of null.

Gatsby image is the best responsive image solution which I have met. It frees you from the tedious optimization work in the build phase, add good performance and excellent user experience to your website. It deserves you to spend time to delve into and use proficiently.

Why More Developers Should Shift to Gatsby

liwenzhi — Sat, 13 Jul 2019 03:10:46 +0000

As the one of the top static site generators, Gatsby have gained much momentum since last year. According to a recent statistics charts show that the average downloads per week reach 200k around. Many web developers are attracted by its slogan: build blazing fast websites and apps, I am among them luckily. At the first impression, it may seems easy to start, but when you delve into it, things not like that.

Why choose Gatsby

7 months ago, I was looking for a web development framework to build a new elearning product, the ideal candidate should meet this tech requirements:

easy to get started
no database dependency
reactjs as front end
markdown file as content source
great performance while running
scalability in customization dev
lower cost for deployment
no need content editor in backend

All this conditions together point to a final solution: a static CMS, then I found the StaticGen. Among the top 5 frameworks, Jekyll, Hugo, Hexo, are not unfamiliar to me. They all use markdown file as content source, but not reactjs tech stack. The first one Next.js, whereas, do not support rendering markdown file to html page by default. In the end, I choose Gatsby as my final dev platform for it meet almost all my requirements.

How to design the project structure

We all know that how to create a reactjs application skeleton using create-react-app. Gatsby also has its cli tool gatsby to complete some tasks like project creation, start dev server, build project to production deployment and such.

A typical gatsby site structure created by $ gatsby new my-gatsby-site may like this:

When you just treat it as a SSR(server side render) framework using reactjs, it's very similar to Next.js. But the truth is that the both are totally different. Actually, Gatsby doesn't render page while request received, it use render at build time approach to output static html content already transformed in build phase. Another difference between the two framework is that:

Gatsby using markdown, json, csv, yaml file, even database as content source. Combined with GraphQL, those contents are mapped to template component and then rendered into static web application.

This is how the Gatsby works in nature, it's more like an engine, leveraging various kinds of plugin to transform different data source to unified data format which can be fetched by GraphQL query, you developer just write template page and GraphQL sentence to display your dynamic content.

Then, back to our project structure, how do we reorganize project so as to let Gatsby render our content file to browser? That's the magical part which make Gatsby unique to other frameworks.

Take the first Gatsby official starter project gatsby-starter-blog for example, we use gatsby new command to clone a gatsby-starter-blog into my-blog-starter directory:

# create a new Gatsby site using the blog starter
$ gatsby new my-blog-starter https://github.com/gatsbyjs/gatsby-starter-blog

The newly created my-blog-starter project ends up a directory structure like this:

The top red rectangle outlines the content directory which contains blog post content in markdown format(.md) and images referenced in post. This is an additional directory not included in the previous my-gatsby-site structure. Besides, templates directory is also a new directory which contains the post template component in charge of fetching markdown file content through GraphQL to reactjs components.

Put content directory in the project root is a good practice in Gatsby project, as well as templates directory under src directory.

Other good practices in planning project structure may include putting hooks and style directory under src directory, hooks contains all the hook components, and style contains all the css module file separated from those template and page components. My preferred src structure may like this:

├── src
  ├── components
  ├── hooks
  ├── pages
  ├── stye
  ├── templates
  ├── utils

Official Gatsby Project Structure document is here

How's the Gatsby dev workflow look like

In the my-blog-starter project, we saw the content .md file and the blog-post.js template. Then, who does the combination task and how does it works? The anwser is in gatsby-node.js.

Basically, gatsby-node.js file act as an assembling factory, it first transform content source into node model, then create page components with template and context parameters originated from node object.

Official document about the Gatsby build lifecycle is here, also the must read Behind the Scenes with Gatsby Internals, gives developer a thorough description of the internal work mechanism.

Here, I would like to summarize the process into a simple graph:

While developing Gatsby applications, we must understand 2 important config files first: gatsby-config.js and gatsby-node.js. One is for website metadata definition and plugins reference, another is for build process callback functions implementation.

That are the major difference from the traditional web development. In traditional web development workflow, we start web server, read application related config such as port number, DB access account and other global parameters, then expose service to client request. But in Gatsby, we don't run service in server, we create content in build time through plugins and callback functions, then deliver them to CDN.

Simply put, Gatsby workflow can be outlined in such a diagram:

Then, our routine iteration development work may start with preparation work which may include writing config file and page templates, as well as content source, then implement callback functions in gatsby-node.js, last run $ gasby develop to see the result.

Among that files, the large amount of time will be taken by template component development. you need to implement UI, interactive logic, write GraphQL sentence in graphql explorer to test the data you want to display, then copy those query sentence and paste into template component for later build use. The template component is like a glue to connect data source and UI layer.

Wait, what if the data is not in file but in DB or 3rd part system? The anwser is using the existing gatsby plugin or developing your own gatsby plugins.

So, to work with Gatsby, you must think in a Gatsby way, just as the above diagram described:

using Plugin to fetch and convert source data to the Gatsby known data model
using Graphql to query UI/template needed data from Gatsby
using build Hooks(callback functions) to generate html content from template components.

What changes does it take to the front devs

Web framework emerging endless, but excellent framework is so rare. In numerous JAMstack solutions, I believe that Gatsby is the most distinctive and innovative. Gatsby claims that it can build website with a blazing fast user experience, Lighthouse test in its official document proved their statement. How did they make it?

The idea behind the product and the architecture pattern they are following ensure its high performance.

For a normal developer, this may mean a lot when you want to develop a prototype web application, deliver user a great user experience without taking pain to tune it little by little, furthermore, you don't have much money to purchase database service and web server.

Take my first Gatsby project UltronEle for example, I toke near 3 months(60~70 workdays) development time to implement the first version of a feature rich elearning product. All my dev time spent in business logic and interactive logic implementation, no need to process database, no need to deploy a server in release environment. This make my product very light, and cost efficient.

Without Gatsby framework, I doubt if my product would be born so soon. Although the initial exploration phase in Gatsby felt a little confusion, but the whole development experience was so cool.

Gatsby's popularity may predict a better internet, the next generation of internet technology, with high speed display, excellent user experience, light weight deployment, lower cost to develop and use. This change would bring web developers and IT service sector plenty of potential opportunities.

Are there any pits still exist

By the time of this post written, unfortunately, there still exist one annoying bug in Gatsby v2.3.27. That's the historic error statement: TypeError: Cannot read property 'childImageSharp' of null.

]

This confused me for a long time, occasionally it popped up and gave you an accidental surprise. It was reported early in issue #2567 on Oct 21, 2017. The solution for that issue ended up with removing .cache folder. So, each time the error jumped out, I would first stop server by ctrl+c then execute the following command and refresh page to get it back:

# in Mac OSX enviroment:
$ rm -rf .cache && gatsby develop

This really works, and is the only approach to eliminate the error so far. The negative impact of this bug to my product is that each time I create tutorial content with generator I must stop server first then create tutorial last execute the command above, lead to a broken user experience.

What's the best practice to persuade clients to use it

From a marketing view, how to sell your Gatsby solution to the best fit clients may be a top priority of concern. This topic has a few of articles discussed in How to Talk about Gatsby to Clients and Your Team and How To Recognize When Gatsby is a Good Fit for Your Client, as well as the Gatsby advantages explanation in one page from its official site.

The internet world by nature consists of a variety of content, text, image, music, video... To push the boundary of distribution for these media content, as well as web resources html, javascript, css, Gatsby was designed to leverge the most advanced web technologies and the most smart design pattern, also referenced the good practice of other CMS framework: themeization to make it more adaptable, reusable, customizable. Then, when you face your potential clients, how could you persuade your clients willing to invest such a technical upgrade, to bear the risk of system transition, and believe the return on investment?

Apart from those How tos, I summarized the following viewpoints to improve the Gatsby adoption in clients business:

leveraging the legacy system content or data by plugin extraction
resolve the performance bottle neck problem through a Gatsby way
start with the internal project, minor functionality unit
introduce to reactjs stack based development team
progressively adoption and migration little by little
aim to clients who want to use cloud service and to cut cost in IT infrastructure

This is a short idea list I can think of currently about traditional web system migration to Gatsby. With more and more projects I involved, I believe this list will continue grow. Web technology is evolving constantly with fun and efficiency, that's how Gatsby comes, let's make it clear and lead a better life in partnership with Gatsby.