DEV Community: Max Shen

How I Fixed GitHub’s 14 Days Repo Traffic Graph

Max Shen — Thu, 10 Jul 2025 13:17:30 +0000

Start of the journey

If you are an open-source maintainer sharing projects on GitHub, you are probably familiar with Github’s repository traffic graph that looks like this:

At first glance, this feature looks useful, but its limitation is clear: it only shows the past 14 days of your repo’s traffic data, making it hard to track long-term trends.

While searching for solutions, I realized that many developers face similar challenges. This issue is widely discussed, particularly in a GitHub thread: Track traffic to GitHub repo longer than 14 days #399.

Exploring alternatives

Within the discussion, I came across a GitHub action that fetches traffic data and stores it in a CSV file, also generating a PDF report:

Now I can view my traffic data more than 14 days, which is a significant improvement.

However, its chart clarity and user interface is pretty bad, and it adds the complexity of setup and accessibility.

This is because, as a GitHub action, I have to manually setup the workflow file. Also, the output being in PDF format made it less accessible and harder to interact with.

Building my own solution

After reflecting on these experiences, I listed out what my ideal tool would look like:

Data access extending beyond 14 days
Intuitive and beautiful chart design
Simple setup

I keep searching tools like this but none of them meets all the requirements. So I decided to build my own!

After few months of working, I finally finished my own tool called Repohistory. Here are some screenshots:

Here’s the approach I took to fulfill all the requirements.

Showing data more than 14 days

It fetches traffic data with GitHub API and stores them in Supabase. This runs every day as a cron job to keep the data up to date.

Intuitive & beautiful chart design

I redesign the whole chart in a modern way and built them with shadcn/ui and Recharts.

Easy to setup

I integrates GitHub Apps into Repohistory, so that user only need to sign in and select the repos they want to track, then it is good to go.

More Features

In additional to tracking repo traffic data, I also add some features to make Repohistory even more useful.

Star history chart

The first one is the repo star history chart. It allows us to see the growth of this repo:

I also add a button to generate sharable image which you can use inside your repo README.md:

Release download chart

The other feature is a chart to show your releases overtime with the total downlaod count on each. Here’s an example from neovim/neovim:

Going forward

Thank you for sticking with me on this ongoing journey of developing a tool to fix GitHub’s repo traffic graph! It’s been a challenging yet enjoyable experience.

However the journey doesn’t end here. I’m continually working on developing and adding some exciting new features to Repohistory. If you’re interested in this evolving project, feel free to check it out and stay updated on GitHub!

You might be overusing Vim visual mode 🤯

Max Shen — Sat, 22 Mar 2025 12:57:39 +0000

When I started learning Vim few years ago, I read through a lot of blog posts and watched a lot of videos. I notice that most of the tutorials teach visual mode in a way that makes it seem like an important part of Vim.

After using Vim for a while, I think this is a mistake. Visual mode is not as important as most people think. In fact, you might be overusing it.

Let me explain why with some examples.

Example 1: Copying whole file

Let's say you want to copy the whole file to system clipboard to ask ChatGPT for help. You might do something like this:

ggVG"+y

Let's break it down:

gg - Go to the beginning of the file.
V - Enter visual line mode.
G - Go to the end of the file.
"+y - Yank the selected text to system clipboard.

However, you can actually achieve the same result with fewer keystrokes:

gg"+yG

Here's the breakdown:

gg - Go to the beginning of the file.
"+yG - Yank from the current position to the end of the file to system clipboard.

Example 2: Deleting current and previous line

Let's say you want to delete current and previous line. You might do something like this:

Vkd

Let's break it down:

V - Enter visual line mode.
k - Move up one line.
d - Delete the selected lines.

However, you can actually do it with fewer keystrokes:

dk

Different mindset

In the above examples, the first editing approach is: v/V + motion + operator. You select text, move the cursor to a specific location, and then do the operation.

The second approach is: operator + motion. This means apply an operation from current cursor position to a specific location. In this way you don't need to enter visual mode at all.

I think the reason why so many people stick to first approach is because when we use general text editors, we are used to selecting text with the mouse and then do the operation. So, when we switch to Vim, we try to do the same thing with visual mode.

However, Vim is not a general text editor. It has a lot of powerful normal mode motion that can help you achieve the same result without selecting text first.

This is a different mindset, but once you get used to it, you will find that you can do things much faster in Vim!

You still need visual mode

While I think you might be overusing visual mode, I'm not saying you should never use it.

If you can't find a motion to achieve what you want, visual mode is a good fallback. Here are some situations where you actually need visual mode:

Select text that is not selectable with simple motion.
Select lines that are out of the current view.
Visually confirm the text you are going to operate on.
Use blockwise visual mode to operate on multiple lines at once.

Bonus tip

If you are too used to visual mode and find it hard to switch to the new mindset. You can try installing hardtime.nvim. It will notify you when there's a better way to do what you are trying to do with visual mode.

For example, if you try to use V5jd, it will show you a warning message:

Use d5j instead of V5jd

In this way you can slowly get used to the new mindset!

Half year reflections on building my first SaaS

Max Shen — Sat, 27 Jul 2024 12:04:55 +0000

It's been around a half year since I started building my dream productivity app, Flowmodor. I think it's a good time to reflect on the journey and share some insights.

Start with some interesting stats:

MRR: $52 (from 11 paying users)
Total registered users: 3700
Average monthly active users: 300
Average monthly landing page visitors: 1000

The overall trend is a slow but steady growth. Here are some reflections on the journey so far.

SEO and traffic

On average, I get 90 new registered users per week, most of them come from organic search:

I think that's because I have been refining the landing page SEO for flowmodoro keyword. It's not a popular term yet so I successfully ranked the top for it.

This is actually a good strategy for a new product. Instead of targeting popular keywords, choosing a niche keyword can help you rank faster and get more targeted users.

In addition to the landing page, I also wrote some blog posts about the Flowtime Technique and Pomodoro Technique. However, the ranking of these posts are not that good. Therefore didn't bring much traffic:

Paying users

I switched from PayPal to Paddle for payment processing. It's a good decision because I can now accept more payment methods and the checkout process is smoother (same for DX). It also provides a better dashboard to track the revenue and users.

Among the 11 paying users, 3 of them are on the yearly plan, which is actually suggested by one of the users. I didn't expect that people would pay for a yearly plan, but it turns out that some users prefer it.

I also added a 14-day free trial for every new registered user. Letting users try the full features for free is a good way to convert them into paying users.

Product development

Although I care about the traffic and revenue, I think the most important thing is still the product itself. It's the real value that I'm providing to users.

The 3 MVP features are all implemented and even more polished. For example the task list now supports Todoist integration, and the focus report now has a yearly heatmap view.

The completion of the MVP features also means that I'll soon have a public launch. I'm planning to launch it on Product Hunt next week. I hope it can bring more exposure and users. You can sign up here to get notified when it's live!

Another important thing is that I've built a feedback board for users to submit feature requests and vote for them:

It's a great way to understand what users really need and prioritize the development. I've already implemented 3 features from the board and I'll start working on the most voted feature: a mobile app, after the public launch.

Conclusion

Building Flowmodor is a challenging but enjoyable journey. This is my first time building a SaaS product and I've learned a lot from it. I'm grateful for all the Flowmodor users providing feedback and support. I'll keep improving the app and looking forward to the PH launch next week 💜

How I grew my open-source project to 1k stars 🌟

Max Shen — Sun, 16 Jun 2024 11:09:17 +0000

Recently, my open-source Neovim plugin hardtime.nvim reached 1k stars on GitHub!

I think it's a good time to share what I have learned about promoting an open-source project. I break down the process into three stages: preparation, promotion, and maintenance. Let's dive in!

Preparation

Before promoting your project, make sure it's ready for the public. Here are some things you should prepare:

1. README

README is the first thing people see when they visit your project. Make sure it's clear and concise. At a minimum, it should include:

One-sentence description of the project
Demo GIF or screenshot
Features of this project
Installation guide
Usage guide

The first two are the most important. They make people quickly understand what your project is about and how it looks like so that they are more likely to continue reading the rest of the README. Here's an example from my project:

For the rest of the README, it might be difficult to write a good one from scratch. Don't worry! You can look at other popular projects in the same domain to get inspiration.

For example, I am inspired a lot by the README of lazy.nvim. Learning from other's success is a good way to improve your project.

It is also important to separate the content into sections using markdown headers. GitHub will automatically generate a table of content, which makes it easier for people to navigate:

2. Contribution guide

If you want people to contribute to your project, you need to provide a contribution guide. It should include:

How to set up the development environment
The coding style of this project
The format of the commit message
What issues are good for beginners

3. Issue template

When people start using your project, they might encounter bugs or have feature requests. To make it easier for them to report issues, you should provide an issue template.

You can create an issue template by following this GitHub docs.

This ensures users provide enough information for you to reproduce the issue and fix it, which makes your later maintenance work easier.

Promotion

After preparing your project, it's time to share it! Here are some strategies you can use:

1. Share with the community

You can share your project on the platform where your target community is active. For example, the Neovim community is pretty active on Reddit, so I shared my project on the r/neovim:

When it comes to sharing on social media, it is crucial to provide a visual element. People are more likely to click on a post with a GIF or image than a plain text post.

For the detail explanation of your project, you can post it in the comment section:

Also remember to engage with the community. If someone asks a question or gives feedback no matter it's positive or negative, make sure to respond to them. This shows that you care about the users and are willing to improve the project.

2. Write articles

When I say write articles, I don't mean you have to write a post about your project. Often, people are not interested in reading a post that is just a promotion of a project. Instead, you can write articles related to the problem your project solves and mention your project in the article.

For example, I wrote an article about practical Vim command workflow. In the article, I share my experience of using Vim operators and motions and how they help me become more productive. At the end of the article, I mention hardtime.nvim as a tool to help establish good command workflow.

In this way you provide value to the readers and promote your project at the same time.

3. Hacktoberfest

Apart from actively promoting your project, you can also leverage events like Hacktoberfest to attract contributors. Hacktoberfest is an annual event that encourages people to contribute to open source throughout October.

By tagging your project with hacktoberfest and providing issues that are good for beginners, you can attract more contributors to your project. Here is an example of the pull requests I received during Hacktoberfest:

Maintenance

Building an open-source project is not a one-time thing. You need to maintain it to keep it alive. User feedback, bug reports, and feature requests will keep coming in, and you need to handle them properly.

Using issue labels can help you organize the issues. For example, you can use bug, enhancement, good first issue, etc., to categorize the issues. This makes it easier for you to prioritize and work on them.

After a while, your project might develop more features or even release a major version. You can then get back to the promotion stage and share the updates with the community.

For example, after my first post about hardtime.nvim, I worked on the users' feedback and added some new features. I then wrote a new post few months later to share the updates:

Just make sure the update are valuable to the users. You don't want to spam the community with minor updates that don't bring much value.

Conclusion

That's pretty much it! I hope you find these tips helpful for promoting your open-source project. Remember, building an open-source project is not just about writing code. A good project is useless if no one knows about it. So don't be shy, share your project with the world!

If you like this kind of content and want to see more of it in the future, consider following my X to get notified when I post new content!

Follow on X

3 Vim commands for blazingly fast navigation between brackets ⚡

Max Shen — Sat, 24 Feb 2024 09:34:03 +0000

There are often lots of brackets within a programming file. Therefore the efficiency of navigating between them becomes crucial for the overall productivity. I'll introduce you to three types of commands that allows you to navigate between brackets blazingly fast!

1. `%`

Let's begin with an example first (the arrow pointing to your cursor position):

( example )
↑

Press %:

( example )
          ↑

Press % again:

( example )
↑

This demonstrates that % jumps between the matched brackets. However the actual behavior is more than that. % find the next item in this line after or under the cursor and jump to its match.

% not only works on (), it also works with:

pairs: () or [] or {} (this can be changed with the 'matchpairs' option)
C-style comment: /* */.
HTML tag: <div></div>

It's crucial to note the emphasis on after or under the cursor, which means that you can use it even when bracket is not under the cursor.

Example:

some text (( example )) some text
↑

Let's say you want to go to the last ). You might initially think to use f(% in the following steps:

Press f(:

some text (( example )) some text
          ↑

Press %:

some text (( example )) some text
                      ↑

However the f( is unnecessary. You can achieve the same navigation with just %.

This is because of % works like this under the hood:

Finds the first pair after or under the cursor which is (.
Jump to its match which is ).

It might not be that intuitive to use % when bracket not under the cursor, but after you get more familiar with it you can achieve some magic movement with it!

2. `[(` and `[{`

[( jumps backward to the first unmatched (
[{ jumps backward to the first unmatched {

Example:

{

  example

  text
  ↑
}

Press [{:

{
↑
  example

  text

}

In addition to [( and [{, there's also ]) and ]}:

]) jumps forward to unmatched )
]} jumps forward to unmatched }

Let's see a practical example. Imagine you're navigating inside a large function:

function example() {
  const sum = 0;
  ↑ 
  for (let i = 0; i < 10; i++) {
    sum += i;
  }

  // some other operation, which takes many lines
  // ...

  return sum;
}

Let's say you want to jump to the closing } of that function. There are several ways to do this:

Use relative jump such as 12j to jump to the } directly:
This approach works for smaller functions. However in the example this is impossible because the function is too big and the last line of the function is outside the screen.
Use /} to search the }:
This might work if there's no other } inside the function. However in the example there's other }, and you need to press n multiple times to get to the last }.
Use ]}:
The most efficient method is to use ]}, which directly takes you to the closing } of the function without the need for counting lines or repeated searching.

3. `][` and `[]`

][: jump forward to the next } in the first column.
[]: jump backward to the next } in the first column.

Example:

{
↑ example
}

{
  {
    example
  }
}

{
  example
}

Press ][:

{
  example
}
↑
{
  {
    example
  }
}

{
  example
}

Press ][ again:

{
  example
}

{
  {
    example
  }
}
↑
{
  example
}

Press ][ again:

{
  example
}

{
  {
    example
  }
}

{
  example
}
↑

This is useful when in files containing multiple functions. In most languages, the end of a function is a } at the start of a line (first column). You can then use ][ to jump to the end of next function and [] to jump to the end of previous function.

There's also:

]]: jump forward to the next { in the first column.
[[: jump backward to the next { in the first column.

Though in practice, the { character appearing in the first column is less common. I personally rarely find an occasion to use them. If you can think of scenarios where ]] and [[ would be particularly useful, please share them in the comments below!

Conclusion

In conclusion, mastering Vim commands such as %, [(, [{, ][, and [] boosts navigation efficiency in programming files. Each command offers unique advantages under different situation, enabling us to move through code with precision and ease!

Understand OAuth 2.0 code grant flow 🔐

Max Shen — Sat, 17 Feb 2024 12:57:02 +0000

If you're building a web application that uses a third-party API, you're likely using the OAuth 2.0 code grant to obtain user permissions. However, its process might not be entirely clear to you. In this post, I'll demystify the process and guide you through the entire OAuth 2.0 code grant flow.

Setting up your application

Before you start working with OAuth 2.0, you first need to sign up your application on the service provider's website. Take Google's APIs as an example; you must register on the Google API Console.

You'll be asked for some simple details about your application, like its name, website, and logo. You'll also need to provide a redirect_uri, which I'll explain in more detail later.

After this, you'll get a client_id and client_secret. These are important because you'll use them in the OAuth 2.0 process.

Complete OAuth 2.0 code grant flow

Once you've set up your application, you're ready to start using OAuth 2.0. Here's what the complete process looks like:

Request authorization and get authorization code.
Exchange authorization code for access token.
Use access token to get user resource through API.

Let's dive into each step, using Google OAuth 2.0 as example.

1. Request authorization and get authorization code

The first step of the web flow is to request authorization from the user. This is accomplished by creating an authorization request link (a GET request) for the user to click on.

GET https://example-service.com/login/oauth/authorize

This endpoint usually takes the following query parameters.

client_id: This is your app's unique identifier, which you receive after registering your app with the service.
response_type: This should be set to code, indicating that you're asking for an authorization code in response.
state: This acts as a security measure and should be a random value for each request. When the user is redirected back to your app, you should verify that the state value matches what you originally sent.
redirect_uri (optional): The URI where you want the user to be redirected after the authorization is complete. This must match the redirect URI that you have previously registered with the service.
scope (optional): Here, you can ask for different levels of access by including one or more scope values (separated by spaces). The specific values depend on the service you're using.

Following the link leads the user to a sign in page:

When the user signs in, the service presents a page detailing your request, including the name of your application, what access you're asking for, etc.

If the user agrees to proceed by clicking Continue, the service redirects them back to redirect_uri, including code (authorization code) and the same state parameter you specified, in the query string.

Here's a flowchart that outlines this first step:

2. Exchange authorization code for access token

The second phase involves exchanging the code you've received for an access_token. This is done by making a POST request to the service's authorization server:

POST https://example-service.com/login/oauth/access_token

This endpoint usually takes the following query parameters.

grant_type: This should be set to authorization_code.
code: The authorization code that you received.
client_id: The unique identifier for your app, provided when you registered with the service.
client_secret: A secret key you received upon registering your app, meant to authenticate your request.
redirect_uri (optional): If you included a redirect URI in the initial authorization request, it must also be included here and match exactly.

The service's response to this POST request will include the access_token you'll use in the final step.

Here's a flowchart summarizing this step:

3. Use access token to get user resource through API

Once you have the access_token, you might save it for later to make API calls. Include it in your request headers like this:

Authorization: `Bearer ${access_token}`

This informs the resource server that you are authorized to access the user's information.

Here's a flowchart illustrating this step:

Now that you understand the basic OAuth 2.0 code grant flow, let's review everything with a diagram showing the full process:

PKCE

The basic authorization flow works well, but it has a vulnerability: if an attacker manages to intercept the code, they can exchange it for an access_token. This poses a serious security risk, potentially allowing the attacker to access protected resources as the user.

This is where PKCE (Proof Key for Code Exchange) comes into play. PKCE is an extension to the basic authorization flow to prevent this kind of attack.

To implement PKCE, the application must first:

creates a code_verifier. This is a cryptographically random string.
use code_verifier to generate the code_challenge by performing a SHA256 hash. If the application cannot perform a SHA256 hash, it should use the plain code_verifier as the code_challenge.

Next, you'll include additional parameters in the previous steps to integrate PKCE:

1. Request authorization and get authorization code

When requesting authorization, include these additional parameters:

code_challenge=XXXXXXXXX: The code challenge generated as previously described
code_challenge_method=S256: This can be either plain or S256, indicating whether the challenge is the plain code_verifier string or a SHA256 hash of it.

The authorization server will associate code_challenge and code_challenge_method with the code it generates.

2. Exchange authorization code for access token

When exchanging the code for an access_token, add the following parameter:

code_verifier: The code verifier for the PKCE request, that the app originally generated before the authorization request.

Since the code_challenge and code_challenge_method were associated with the code initially, the server should already know which method to use to verify the code_verifier.

For the plain method, the authorization server simply verifies that the provided code_verifier matches the previously stored code_challenge.
For the S256 method, the authorization server will hash the provided code_verifier using SHA256 and then compare it to the stored code_challenge.

If the verification is successful and the values match, the server issues an access_token. If they don't match, the request is denied.

This mechanism ensures that even if an attacker intercepts the code, they cannot exchange it for an access_token without the code_verifier.

Conclusion

In summary, the OAuth 2.0 code grant flow is a crucial process for you to understand and implement when building web applications that require access to user data from third-party services. By following the outlined steps and incorporating PKCE, you can securely authenticate users and access necessary resources while protecting against common security vulnerabilities.

Tailwind CSS under the hood

Max Shen — Sat, 10 Feb 2024 14:00:07 +0000

Tailwind CSS defines itself on its official site as:

A utility-first CSS framework packed with classes.

In this post I'll explain to you what does utility-first mean and how Tailwind CSS works under the hood.

Utility-first

Utility classes are easily understood, single purpose classes. For example, Tailwind provides utility classes such as:

.mx-auto {
  margin-left: auto;
  margin-right: auto;
}

.text-sm {
  font-size: 0.875rem;
  line-height: 1.25rem;
}

So when you want to horizontally center a paragraph with small font size, you can just use mx-auto text-sm as the class name of the element.

In this way, we can build complex components by combining different utility classes together.

3 main benefits of utility-first

Now we understand what is utility-first and let’s see the benefits of it:

1. Design with constraints

Using inline styles, every value is an arbitrary number. With utilities, you’re choosing styles from a predefined design system such as the default spacing scale:

Take setting width for an example, you just use utility class such as w-48 or w-96, instead of specify the exact pixel you want. This makes it much easier to build visually consistent UIs.

2. CSS stops growing

Using a traditional approach, your CSS files get bigger every time you add a new UI component. With utilities, everything is reusable. This means the size of your CSS file stops growing after a certain point because the same utility classes are used again and again.

3. No need to invent class names

With traditional CSS, you might be adding class names like sidebar-inner-wrapper just to be able to style a <div>. With utilities, you just composing them to build a complex style you want.

How Tailwind CSS works under the hood

Tailwind CSS works by scanning all of files for class names at build time, then generating all of the corresponding CSS for those styles.

The paths to all of your content files is specified by content section of your tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./pages/**/*.{html,js}", "./components/**/*.{html,js}"],
  // ...
};

Tailwind use regular expression to detect class names. Therefore when you want to use utility class conditionally like the following syntax doesn’t work:

<div className={`text-${error ? "red" : "green"}-600`}>Lorem Ipsum</div>

This is because the regular expression doesn’t match any class name.

Instead, you should use:

<div className={error ? "text-red-600" : "text-green-600"}>Lorem Ipsum</div>

In the second approach, Tailwind can match the string 'text-red-600' and 'text-green-600' and then generates the corresponding CSS.

This also explains why you can't use props to build class names. For example, this won't work:

function Button({ color, children }) {
  return (
    <button className={`bg-${color}-600 hover:bg-${color}-500 ...`}>
      {children}
    </button>
  );
}

Instead, map props to complete class names that are statically detectable at build-time:

function Button({ color, children }) {
  const colorVariants = {
    blue: "bg-blue-600 hover:bg-blue-500",
    red: "bg-red-600 hover:bg-red-500",
  };

  return <button className={`${colorVariants[color]} ...`}>{children}</button>;
}

Wrap up

To sum up, we've learned that Tailwind CSS makes it easy to design neat and consistent websites. Knowing how it works also helps us understand why some things work well and others don't, guiding us to use Tailwind more effectively!

5 things to do during Pomodoro break without electronic devices

Max Shen — Sun, 28 Jan 2024 13:04:08 +0000

When practicing productivity techniques like the Pomodoro or Flowmodoro methods, it's easy to dismiss the importance of breaks.

During these breaks, it's tempting to immediately reach for your phone and spend the entire time scrolling, rationalizing it as a reward for your prior concentration.

However, this habit not only makes it challenging to regain focus for the next session but also denies your eyes the rest they need. Therefore, I'll introduce five activities you can engage in during your breaks, all without the use of electronic devices.

1. Stretch your body 🤸

Stretching during breaks is not just a way to relieve physical tension but also to clear your mind. The nature of programming often demands extended durations of seated concentration, which can lead to physical rigidity. Simple stretching exercises can relieve muscle tension and also provide a mental reset, preparing you for the next phase of intense focus.

2. Go for a walk 🚶

A short walk is an excellent way to disconnect from your work. It's not just about the physical movement but also about changing your environment. Walking away from your workspace allows you to return with a fresh perspective. Whether it's a stroll around your office, a quick venture into your backyard, or just pacing in your room, the act of walking helps in resetting your mind, making you more creative and productive when you return.

3. Look off into the distance 🔭

Taking a quick break to look away from your computer screen is simple but really helpful. When you've been staring at code for a while, it's good to give your eyes a rest. Try to find a spot where you can look out a window. Focus on something far away like the sky, trees, or distant buildings. This isn't just about resting your eyes; it's also a quiet moment for your mind. As you look away, take a few deep breaths. This easy break can help you feel more relaxed.

4. Organize your work desk 🧹

A cluttered desk can lead to a cluttered mind. Use your break to organize your workspace. Put away unnecessary items, arrange your documents, and clear any trash. A clean and organized environment can significantly boost your productivity and reduce stress levels.

5. Fill your water bottle & visit the restroom 💧

Hydration is key to maintaining high energy levels and focus. Use your break to refill your water bottle. It's a simple act, but it ensures that you stay hydrated, especially important if you're so engrossed in your work that you forget to drink water. Additionally, a regular visit to the restroom is also important.

Wrapping up

In short, taking breaks is key to doing well at work or study. Using breaks wisely, by doing things like stretching, walking, looking into the distance, tidying up your desk, or getting water, isn't just a rest from work. It's a way to make sure you come back to your tasks with more focus and energy.

These simple actions during breaks can help you feel better and work better. So, remember to step back, take a good break, and see the difference it makes in your day!

Why pomodoro doesn't work? Try this alternative 🍅

Max Shen — Sun, 14 Jan 2024 12:00:57 +0000

What's Pomodoro

The Pomodoro Technique, developed by Francesco Cirillo, is a time management method that uses a timer to break work into intervals, traditionally 25 minutes in length, separated by 5-minutes short breaks.

These intervals are known as "pomodoros", named after the tomato-shaped kitchen timer that Cirillo used as a university student.

Why Pomodoro might not work for developers

While the Pomodoro Technique is popular, it might not be the best fit for everyone, especially developers. Here’s why:

Interruption of Flow State: The rigid timing can disrupt the deep "flow state" crucial for coding. When you're deeply engrossed in a complex problem, stopping because a timer goes off can break your train of thought.
Variable Task Length: Coding tasks vary in complexity and often don't neatly fit into 25-minute intervals. Some tasks might require prolonged uninterrupted focus, while others are shorter and more straightforward.
Context Switching: Frequent breaks mandated by the Pomodoro Technique can lead to excessive context switching. This is counterproductive for tasks that require sustained concentration and a deep understanding of the problem at hand.

The better alternative - Flowmodoro

The Flowtime Technique a.k.a. Flowmodoro was created by Zoë Read-Bivens as a solution to Pomodoro's main problem.

Unlike the Pomodoro Technique, Flowmodoro counts up instead of counting down. It allows you to focus until you naturally feel the need for a break. Then, when you decide to rest, you simply stop the timer, divide the focus time by 5, and set a countdown timer for your break.

This method respects your flow state and adapts to the variable nature of coding tasks.

How to implement Flowmodoro

Implementing Flowmodoro is simple and can start with tools as basic as a stopwatch and timer app. Here's a basic guide:

Pick One Task: Begin by selecting a single task to focus on. This ensures that your attention isn't divided across multiple tasks.
Start the work: Once your task is chosen, start the stopwatch. This marks the beginning of your focused work period. Dive into your task without any distractions.
Stop the work: Keep working until you naturally feel the need for a break. This could be when you feel your concentration waning or you've reached a logical stopping point in your task. Then, stop the stopwatch. This time recorded is your focused work duration.
Take a break: Calculate your break time as one-fifth of your focused work duration. For instance, if you worked for 50 minutes, take a 10-minute break. Set a countdown timer for this break period. This ratio ensures that you get adequate rest without losing the momentum of your work.

You can repeat this cycle again and again.

Automate the process

I have been using Flowmodoro and it really help me improve my productivity while coding. However, I noticed one minor drawback: the repetitive process of setting up the timer manually each time.

To address this, I'm currently working on a solution that seamlessly integrates with this workflow. That's where Flowmo comes in – a web app I am creating to automate and refine the Flowmodoro process.

Get Started

As developers, our work requires flexibility and adaptation. Flowmodoro is designed with this in mind. Let's embrace our peak flow states with Flowmodoro!

Build a Neovim plugin in Lua 🌙

Max Shen — Tue, 10 Oct 2023 11:08:35 +0000

TL;DR

In this article, you'll learn how to develop a Neovim plugin in Lua, understand the structure of Neovim plugin, Lua module, and create a simple plugin.

Let’s set it up 🔥

Before developing the plugin, we need to set up the project. There are two different approaches:

setup with GitHub repository
setup locally

Setup with GitHub repository

Create a new repository on GitHub (e.g.: example.nvim)
Install it with a plugin manager

-- lazy.nvim
{
   "m4xshen/example.nvim" -- replace this with your {user_name}/{repo_name}
}

cd to the directory where the plugin is installed

cd ~/.local/share/nvim/lazy/example.nvim

Setup locally

Create a new directory on your local machine

mkdir ~/example.nvim

Install it with a plugin manager

-- lazy.nvim
{
   dir = "~/example.nvim"
}

cd to the directory

cd ~/example.nvim

Plugin structure 🏗️

Now the plugin is setup and installed. Let's learn about its folder structure.

At the root of your plugin, create a structure like this (replace the example with your plugin name):

example.nvim/
├── lua
│   └── example
│       └── init.lua
└── plugin
    └── example.lua

`plugin/`

The files inside plugin/ folder will be executed when Neovim starts. Try to add the following line to example.lua:

print("plugin/example.lua is executed!")

Open a new Neovim instance after that, you'll see the string printed because Neovim runs the Lua code of the file.

`lua/`

Most of the time you don't want the plugin to execute everything at startup. You want it to run some functions when events happened, command called, etc. and organize the code in a structured way. That's where Lua module comes into play.

A Lua module is a regular Lua table that is used to contain functions and data. The table is declared local not to pollute the global scope. For example:

local M = {} -- M stands for module, a naming convention

function M.setup()
   print("hello")
end

return M

If you want to load Lua module on demand, you can place them inside the lua/ directory in your 'runtimepath' and load them with require.

Rules of `require`

Here are the rules when require finding files:

Any . in the module name is treated as a directory separator when searching.
When the file with module name is not searched, it then searches for init.lua inside the folder with module name.
You don't need to type the .lua extension.

Example: For a module foo.bar, each directory inside 'runtimepath' is searched for lua/foo/bar.lua, then lua/foo/bar/init.lua.

So if you put the code above into lua/example/init.lua, you can run :lua require("example").setup() to print hello. That is because the plugin manager added the folder of the plugins into 'runtimepath' for you. Therefore the require can find this file.

Example 💡

After understanding the structure of Neovim plugin, let's finish the example.nvim! This plugin does 2 simple things:

It maps the <Leader>h to print hello to the user.
If user specify their name when setting up plugins, it prints hello, {user_name} instead.

Here's the lua/example/init.lua:

local M = {}

function M.setup(opts)
   opts = opts or {}

   vim.keymap.set("n", "<Leader>h", function()
      if opts.name then
         print("hello, " .. opts.name)
      else
         print("hello")
      end
   end)
end

return M

You need to call setup after installing plugin:

require("example").setup()

Or if you are using lazy.nvim:

{
   "m4xshen/example.nvim",
   opts = {}
}

Notice that we use vim.keymap.set which is only available after Neovim 0.7.0. We need to add a version checker and it should be executed automatically at startup, so it should be put inside plugin/ folder.

Here's the plugin/example.lua:

if vim.fn.has("nvim-0.7.0") ~= 1 then
   vim.api.nvim_err_writeln("Example.nvim requires at least nvim-0.7.0.")
end

After that this simple plugin is finished. Now try pressing <Leader>h and the greeting message should be printed! You can also set your name inside setup function so that it prints greeting message with name:

require("example").setup({
   name = "Max",
})

Or if you are using lazy.nvim:

{
   "m4xshen/example.nvim",
   opts = {
      name = "Max",
   }
}

Check out the complete source code.

Final Words 🚀

Getting started is the hardest part when developing a Neovim plugin first time. I hope this tutorial helps you out. If you have any questions, feel free to ask in the comment section.

That’s a wrap. Thanks for reading. If you like this kind of stuff, consider following for more.

You can also see what I am working on my Personal Website and GitHub.

Setup Next.js with Airbnb ESLint, Prettier, TypeScript and Tailwind CSS

Max Shen — Sun, 10 Sep 2023 13:40:03 +0000

In this tutorial you'll learn how to setup a Next.js project with Airbnb ESLint, Prettier, Typescript and Tailwind CSS in a correct way so that you don't need to turn off a lot of rules inside .eslintrc.json anymore.

Create Project

I recommend starting a new Next.js app using create-next-app, which sets up everything automatically for you.

npx create-next-app@latest

Remember to select Yes for these 3 prompts to have a basic setup for TypeScript, ESLint and Tailwind CSS:

Would you like to use TypeScript? No / Yes
Would you like to use ESLint? No / Yes
Would you like to use Tailwind CSS? No / Yes

Prettier

Prettier is an code formatter. You can install it with your package manager:

yarn add --dev --exact prettier

npm install --save-dev --save-exact prettier

Then, create a config file named .prettierrc.json.

Check out all possible config options. If you don't need to set any options, just leave a {}.

Example:

{
  "singleQuote": true,
}

At this point you can run the Prettier and it should works!

yarn prettier . --write

npx prettier . --write

You can also setup Prettier for your editor so that you can run Prettier efficiently with keymap. See docs.

Tailwind CSS

There's an official Prettier plugin for Tailwind CSS that scans your files for class attributes containing Tailwind CSS classes, and then sorts those classes automatically following the recommended class order.

Install the plugin:

yarn add --dev prettier prettier-plugin-tailwindcss

npm install --save-dev prettier prettier-plugin-tailwindcss

Add the following line into the prettier config:

"plugins": ["prettier-plugin-tailwindcss"]

Now the example config becomes:

{
  "singleQuote": true,
  "plugins": ["prettier-plugin-tailwindcss"]
}

If you run Prettier now, the Tailwind CSS classes name will be sorted!

ESLint

ESLint is a tool for identifying and reporting on patterns found in ECMAScript code, with the goal of making code more consistent and avoiding bugs.

You can add community plugins, configurations, and parsers to extend the functionality of ESLint.

Airbnb's rules for ECMAScript 6+ and React

npx install-peerdeps --dev eslint-config-airbnb

Add airbnb and airbnb/hooks to .eslintrc.json:

{
  "extends": [
    "airbnb",
    "airbnb/hooks",
    "next/core-web-vitals"
  ]
}

(next/core-web-vitals is the default rule set by create-next-app)

If you run lint now:

yarn run lint

npm run lint

You'll see error like:

JSX not allowed in files with extension '.tsx'

which means that we don't have the TypeScript support in our setting now.

Airbnb's rules for TypeScript

Install:

yarn add eslint-config-airbnb-typescript \
            @typescript-eslint/eslint-plugin@^6.0.0 \
            @typescript-eslint/parser@^6.0.0 \
            --dev

npm install eslint-config-airbnb-typescript \
            @typescript-eslint/eslint-plugin@^6.0.0 \
            @typescript-eslint/parser@^6.0.0 \
            --save-dev

Add airbnb-typescript and parserOptions to .eslintrc.json:

{
  "extends": [
    "airbnb",
    "airbnb-typescript",
    "airbnb/hooks",
    "next/core-web-vitals"
  ],
  "parserOptions": {
    "project": "./tsconfig.json"
  }
}

Integrate Prettier with ESLint

Finally, we need to turn off all rules that are unnecessary or might conflict with Prettier, which can be done with the following package:

yarn add --dev eslint-config-prettier

npm install --save-dev eslint-config-prettier

Add it to .eslintrc.json:

{
  "extends": [
    "airbnb",
    "airbnb-typescript",
    "airbnb/hooks",
    "next/core-web-vitals",
    "prettier"
  ],
  "parserOptions": {
    "project": "./tsconfig.json"
  }
}

Each rule will extend or overwrite the previous ones, and in this situation we want to turn off the rules that might conflict with Prettier, so we should put it at the end of the list.

Final Words

After following this tutorial, you should setup an awesome environment for developing Next.js project. All of the installation and setup commands are taken from the following official docs. You can check them out for more detail explanation:

That’s a wrap. Thanks for reading. If you like this kind of stuff, consider following for more.

You can also see what I am working on my Personal Website and GitHub.

Build your modern Neovim config in Lua

Max Shen — Sun, 26 Feb 2023 11:26:45 +0000

In this tutorial you'll learn how to build and structure your modern Neovim config in Lua. I'll go through options, mappings, autocmds and plugins. You can read along with my configuration. To learn more about what each option does, use :h 'option name' in Neovim.

How Neovim loads config

Neovim supports using init.lua as the configuration file. This should be placed in your config directory:

Linux, BSD or macOS: ~/.config/nvim
Windows: ~/AppData/Local/nvim/

Although you can put all the settings inside init.lua, you probably don't want to because the file will become large and difficult to manage.

To avoid this, separate files to multiple modules and then load them in the init.lua using require. You can place those modules in the lua/ directory in your runtimepath (a list of directories to be searched on startup).

My Neovim config structure:

~/.config/nvim
|-- init.lua
|-- lua/
|  |-- config/
|  |  |-- options.lua
|  |  |-- mappings.lua
|  |  |-- autocmds.lua
|  |  |-- lazy.lua
|  |-- plugins/
|     |-- autoclose.lua
|     |-- lsp.lua
|       :

The first line of init.lua:

require("config.options")

When Neovim reads this line on startup, it goes through the runtimepath, search for lua/ and load /config/options.lua. The default runtimepath includes includes ~/.config/nvim. This is why we put the lua/ inside it.

Notes:

. in the module name is treated as a directory separator when searching.
You don't need to type the .lua extension.

Now we understand how Neovim finds our files. We can start configuring it! Note that all the directories specified below start from the Neovim config directory.

Options

You can set options via Lua in two ways: vim.opt and vim.o series. I recommend using vim.opt series because it is more Lua-style, you can:

use :append(), :prepend() and :remove() to manipulate options
set its value to Lua table

(see the differences between them with :h lua-guide-options)

You can set options with vim.opt.option-name = value.

Part of my lua/config/option.lua:

-- enable line number and relative line number
vim.opt.number = true
vim.opt.relativenumber = true

-- use global statusline
vim.opt.laststatus = 3

-- disable mouse
vim.opt.mouse = ""

Remember to require("config.options") in init.lua.

Keymap

Define your leader key: (I use space. Change this to whatever you like.)

vim.g.mapleader = " "

Add a new mapping:

vim.keymap.set({mode}, {lhs}, {rhs}, {opts})

{mode} (string or table) mode short-name
- "" for Normal, Visual, Select, Operator-pending mode
- "n" for Normal mode
- "v" for Visual and Select mode
- "s" for Select mode
- "x" for Visual mode
- "o" for Operator-pending mode
- "i" for Insert mode
- "t" for Terminal mode
- "!" for Insert Insert and Command-line mode
{lhs}: (string) left-hand side of the mapping, the keys we want to map
{rhs}: (string or function) right-hand side of the mapping, the keys or function we want to execute after pressing {lhs}
{opts}: (table) optional parameters
- silent: define a mapping that will not be echoed on the command line
- noremap: disable recursive mapping

See all available options with :h map-arguments.

Part of my lua/config/mappings.lua:

-- map leader+w to save current file in normal mode
vim.keymap.set("n", "<Leader>w", ":write<CR>", { noremap = true, silent = true })

-- map leader+y to copy to system clipboard in normal and visual mode
vim.keymap.set({ "n", "v" }, "<Leader>y", '"+y', { noremap = true, silent = true })

Remember to require("config.mappings") in init.lua.

Auto commands

Create an autocommand event handler:

nvim_create_autocmd({event}, {*opts})

{event}: (string or array) events that will trigger the handler

BufEnter: after entering a buffer
CmdlineLeave: before leaving the command-line

See all available events with :h autocmd-events.

{opts}: options

pattern (string or array): pattern to match
callback (function or string): Lua function called when the event is triggered

See all available options with :h nvim_create_autocmd.

Part of my lua/config/autocmds.lua:

-- set tab to 3 space when entering a buffer with .lua file
vim.api.nvim_create_autocmd("BufEnter", {
   pattern = { "*.lua" },
   callback = function()
      vim.opt.shiftwidth = 3
      vim.opt.tabstop = 3
      vim.opt.softtabstop = 3
   end
})

Remember to require("config.autocmds") in init.lua.

Plugins

At this point, you should already have a basic Neovim setup. However you can install plugins to make it even better!

I use lazy.nvim to manage my plugins. We need to install it first. Remember to require("config.lazy") in init.lua.

-- `lua/config/lazy.lua`

-- install lazy.nvim
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
if not vim.loop.fs_stat(lazypath) then
   vim.fn.system({
      "git",
      "clone",
      "--filter=blob:none",
      "https://github.com/folke/lazy.nvim.git",
      "--branch=stable", -- latest stable release
      lazypath,
   })
end
vim.opt.rtp:prepend(lazypath)

-- load plugins
require("lazy").setup("plugins")

The command on the last line loads all the .lua file under lua/plugins/ and the returned table will be merged and passed to setup().

Example:

-- lua/plugins/autoclose.lua

return {
   {
      "m4xshen/autoclose.nvim",
      opts = {
         options = {
            disabled_filetypes = { "text", "markdown" },
            disable_when_touch = true,
         }
      },
   },
   { "windwp/nvim-ts-autotag" },
}

In the returned table, the first line is the plugin's short url and the rest are arguments(optional) to set plugins up:

config: Function that is executed when the plugin loads. The default implementation will run require("plugin").setup(opts).
opts: Passing options to the config function.
init: Functions that is executed during startup.

Check out all available option on lazy.nvim's README.md.

Follow this pattern to install and set other plugins up. You can also see my plugins config files to get some ideas.

Final Words

Now you have a modern Neovim configuration file written in Lua! If you want to explore more, you can install plugins like nvim-treesitter and nvim-lspconfig. These plugins can give you better experience when coding.

Discover more plugins on:

That’s a wrap. Thanks for reading. If you like this kind of stuff, consider following for more.

You can also see what I am working on my Personal Website and GitHub.

DEV Community: Max Shen

How I Fixed GitHub’s 14 Days Repo Traffic Graph

Start of the journey

Exploring alternatives

Building my own solution

Showing data more than 14 days

Intuitive & beautiful chart design

Easy to setup

More Features

Star history chart

Release download chart

Going forward

You might be overusing Vim visual mode 🤯

Example 1: Copying whole file

Example 2: Deleting current and previous line

Different mindset

You still need visual mode

Bonus tip

Half year reflections on building my first SaaS

SEO and traffic

Paying users

Product development

Conclusion

How I grew my open-source project to 1k stars 🌟

Preparation

1. README

2. Contribution guide

3. Issue template

Promotion

1. Share with the community

2. Write articles

3. Hacktoberfest

Maintenance

Conclusion

3 Vim commands for blazingly fast navigation between brackets ⚡

1. %

2. [( and [{

3. ][ and []

Conclusion

Understand OAuth 2.0 code grant flow 🔐

Setting up your application

Complete OAuth 2.0 code grant flow

1. Request authorization and get authorization code

2. Exchange authorization code for access token

3. Use access token to get user resource through API

PKCE

1. Request authorization and get authorization code

2. Exchange authorization code for access token

Conclusion

Tailwind CSS under the hood

Utility-first

3 main benefits of utility-first

1. Design with constraints

2. CSS stops growing

3. No need to invent class names

How Tailwind CSS works under the hood

Wrap up

5 things to do during Pomodoro break without electronic devices

1. Stretch your body 🤸

2. Go for a walk 🚶

3. Look off into the distance 🔭

4. Organize your work desk 🧹

5. Fill your water bottle & visit the restroom 💧

Wrapping up

Why pomodoro doesn't work? Try this alternative 🍅

What's Pomodoro

Why Pomodoro might not work for developers

The better alternative - Flowmodoro

How to implement Flowmodoro

Automate the process

Build a Neovim plugin in Lua 🌙

TL;DR

Let’s set it up 🔥

Setup with GitHub repository

Setup locally

Plugin structure 🏗️

plugin/

lua/

Rules of require

Example 💡

1. `%`

2. `[(` and `[{`

3. `][` and `[]`

`plugin/`

`lua/`

Rules of `require`